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IfyiROOUCTION 

HIS provides a variety of comrsands for file manipulation and 
viewing* Editing coiRfiands allow the user to Insert and change the 
text In a file. Viewing comiuands Cvlewspecs) allow the user to 
control how the system prints or displays the file* tine truncation 
and control of statement numbers are exaniples of these viewing 
facilities* 

Occasionally one may need more sophisticated view controls than 
those available with the viewing features of NLS* 

For exaiRplet one way want to see only those statements that 
contain a particular word or phrase* 

Or one might want to see one line of text that compacts the 
Information found In several longer statements* 
One ffflght also wish to perform a series of routine editing 
operations without specifying each of the NLS coffifnands over and over 
agalnt or build commands for specific applications* 

User-written programs may tailor the presentation of the Information 
In a file to particular needs* Experienced users fpay write prografps 
that edit files automatically* 

User-written programs currently must be coded In ARC'S 
procedure-oriented programnilng language? LIO* MLS Itself Is coded 
In LIO* LIO Is a high-level language which inust be compiled Into 
machine-readable Instructions* This docufisent describes LIO* 
Prograffis which Interact with users additionally use a language 
developed at ARC called Cofismand Heta Language tCHLl^f described 1n 
Part Four of this document* 
This docufnent describes three general types of programs: 

—simple filters that control what Is portrayed on the user^s 

teletype or display (Parts One and Two>* 

— programs that may modify the statements as they decl ce whether 
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to print the!i{ CParts Two and Three>f 

— those thatf like comsiandSf are explicitly given control of the 

Job and interact with the user (Part Four>» 

User programs that control what material Is portrayed take effect 

when NLS presents a sequence of statements In response to a 

command tike Print Cor Juiup In DMLS) • 

In processing such a cofnniandf MLS looks at a sequence of 
statementSf exasulnlng each statement to see If It satisfies 
the viewspecs then In force* At this point MLS may pass the 
statement to a user-written program to see If It satisfies the 
requlreiuents specified In that prograi!}* If the user program 
returns a value of TRUE* the (passed) statement Is printed and 
the next stateiBent In the sequence Is tested* If FALSEt NLS 
just goes on to the next statement. 
yh1le the programs Is examining the statement to decide whether or 
not to print Itt it may modify the contents of the stateiient* 
Such a program can do anything the user can do with WLS cos?mands» 
For more complex taskst a user program function as a 
special-purpose subsystem having (In addition to the may 
supervisor comffiands) one or more coiriffiands* Once such a program 
Is loadedt It can be used 5ust like any of the standard 
subsystems* (The MESSAGE program Is an example*) 
This document Is divided Into five parts: 

Part One Is Intended for the general user* 

It 1s a primer on Content Analyzer Patterns* allowing the MLS 
user to set up simple yet powerful filters whrough which he 
may view and edit files* This does not Involve learning the 
LIO language nor prograsming* This section can stand alone* 
and the general (if sofsewhat experienced) NLS user should find 
1t very useful* 
Part Two Is Intended for the beginning prograaiaier* 

It presents a hasty overview of LIO prog ram Ming* with enough 
tools to write simple prograsts* This is Intended as an 
Introduction for the beginning user p rog ram me rt who we assume 
1s reasonably faireillar with f4LS (its cosusandst subsystesist and 
capabilities) and has some aptitude for prograinmlng • 
Part Three Is a more complete presentation of LIO* 

It is intended to acquaint a potential LIO prograniffler with 
enough of the language and MLS environsient to satisfy most 
requirements for automated editing programs* Hany of the 
concepts in Part Two are repeated in Part Three so that it may 
stand alone as an intermediate programmer's reference guide* 
This Is the section In which to begin looking for answers to 
specific questions* 
Part Four presents more advanced LIO tools and an introduction to 
CHL» allowing command syntax specification. 

This should give the programmer the ability to write prografns 
which work across filest which move through files in other 
than the standard sequential order* and which interact with 
the user* It allows the programmer to build user-attachable 
subsystems with commands looking very much like standard NLS 
f aci lit ies* 
Part Five presents a number of subjects of interest to the 
advanced LIO progammer* 

ye suggest that those who are new to LIO begin by acquiring a 
thorough understanding of Part One* Then Part Two should be 
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studied one section at a timet pausing between sections to try 
out the concepts presented by actually writing patterns or 
prografRS that put the ney Ideas to experimental use* Actual 
experience Is of at least as liuch value as this tutorial. 
Tutorial guidance should be requested from ARC through your 
architect. If you have problems at any polntt you should get 
help from ARC before proceeding to the next section. 

Note: For syntactical correctnesst sosje examples include 
constructs not yet defined in the text? they will be discussed 
soon thereafter. 
For examples of user programs which serve a variety of needst 
exafulne the attachable subsystems In the <PROGRAHS> directory and 
their descriptions In Help* For Information about comfnancs 
mentionedf ask for the programming subsystem with the f^LS Help 
cotisfntand. f^DH 
PART one: Content Analyzer Patterns 
Section i: Introduction 

Content analysis patterns cannot affect the for«at In which a 
statement is printed* nor can they edit a file. They can only 
determine whether a statement should be printed at all* They 
are* In a senset a filter through which you may view the file. 
More cosiplex tasks can be accomplished through program st as 
described later In this document. 

The Content Analyzer filter Is created by typing in Cor selecting 
frofi! the text in a file) a string of a special foriti which 
describes those statements which will pass through the filter. 
This string is called the "Content Analyzer Pattern*** Each 
statement Is checked against the pattern before it is printed! 
only statements that are described by the pattern will be 
printed. 
Some quick examples of Content Analyzer Patterns: 

♦< $LD •) will show all statements whose first character 1s 
an open parenthesist then any number of letters or digltst 
then a close parenthesis. 

C^blap"! will show all stateaients with the string "blap" 
soffiewhere in them. 

SINCE <5-JUN-75 OOrOO) will show all statements edited since 
June 3» 1975 
The next part of this section will describe the elenents which 
make up Content Analyzer Patternst followed by sojse examples. 
The final subject of this section is how to put the?i to use. 
Section 2: Patterns 

Elements of Content Analyzer Patterns 

Content Analyzer Patterns describe certain things the system 
Rsust check before printing a statement* It Biay check one or a 
series of things. Each test is called an eleffient* the Biany 
possible elements will be described below. 

The Content Analyzer searches a stateipent from the 
beginning* character by character* for described elements* 
As it encounters each element of the pattern* the Content 
Analyzer checks the statement for the occurrence of that 
eleiRent? If the test fails* the whole statement 1s failed 
(unless there was an "or** condition* as described later) 
and not printed; if the test is passed* an imaginary 
marker moves on to the next character In the statement* and 
the next test in the pattern Is considered. 
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For exainplef If the next eLefrtent In the Content Analyzer 
pattern is "LD^t the Imaginary marker w1 it (Bove ever the 
next character and 90 on to test the next eleiient of the 
pattern only If the next character 1s a letter or a dlfltl 
otherwise the whole statement falls to pass the filter* 
The pattern may Include any sequence of the following 
elements! the Content Analyzer woves the marker through the 
statersent checking for each element of the Pattern In turn: 
Literal String elements 

♦c -- the given character Ce«g* a loyer case c) 
"string" — the given string Cfftay Include non-printing 
characters* such as spaces) 
Character class elements 
CH -- any character 
L — lowercase or uppercase letter 
— digit 

Ut -- uppercase letter 
LL -- lowercase letter 
ULD — uppercase lettert or digit 
LLD — lowercase letter* or digit 
LD -- lowercase or uppercase letter* or digit 
NLD — not a letter nor digit 
PI •"■ any printing character i letters* digits* punctuation) 

HP -- any non~pr1nt1ng character te»g» spaces* control 
characters) 
Special non-pr1nt1ng character elements 
SP -- a space 
TAB -- tab character 
CR -- a carriage return 
LF -- line feed character 
EOL — TENEX EOL iend of line) character 
ALT -- altiBode character 
Special elefnents 

Ef^DCHR — beginning and end of every NLS state^ient* can»t 
scan past it I not considered a character 
TRUE — 1s true without checking anything In stateiiient 
(used with OR constructs* as described below) 
10= 1d -- stateisent created by user whose Ident 1s given 
I0# Id — stateisent not created by user whose Ident Is 
given 

BEFORE (d-t) »- statement edited before given date and t1ii*e 
SI^CE (d-t) — statement edited since given date an6 tlaie 
E.g. BEFORE (1 OCT 1974 00:00) ; 

The date and time must both appear In the parentheses* 
It accepts almost any reasonable date and time syntax* 
Examples of valid dates: 

17-APR-74 17 APRIL 74 

APR-17-74 17/5/1974 

APR 17 74 5/17/74 

APRIL 17* 1974 
Examples of valid times: 

1:12:13 1234:56 

1254 i:5SAH 

i:56-EST 120051OGN 

16:30 (1«e» 4:50 PH) 
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12:00:00 AM Ci.e» midnight J 
li:59:59AH-EST <1«e« late irorning) 
12:00:01AM (1«e» early rooming) 
Scan direction 

< — set scan direction to the left 
> — set scan direction to the right 

The defaultf re-initialized for each new statement « is 

scan to the right from before the first character in the 

statement (beginning to endl* 
Hodifying Elements 

Several operators can roodify any of the eleisents except the 

"special eles»ents*»: 

MUHBER — multiple occurrences 

A nufflber preceding any eleiRent other than one of the 
"Special elements" lueans that the test will succeed only if 
it finds exactly that many occurrences of the element. If 
there aren't that Bianyt the statement will be rejected* 
Even though there may be fsoret it will stop after that ^any 
and go on to check the next element in the pattern* 

3UL means three upper case letters 
$ — range of occurrences 

A dollar sign ($> preceding any element other than the 
"Special elesients" means "any number of occurrences of»» 
This may include zero occurrences* It is good practice to 
put the element itself in parentheses* 

$(♦-) means any number of dashes 
A number in front of the dollar sign sets a lower limit* 

3S(D) means three or more digits 
A number after the dollar sign sets an upper limit for the 
search* It will stop after that number an6 then check for 
the next element in the patternt even if it could have 
found more* 

$3tLD) means from zero to three letters or digits 

5$7(PT> means from 5 to 7 (inclusive) printing 

characters 
11 — floating scan 

To do other than a character by character check* you nay 
enclose an element or series of elements in square brackets 
CI* The Content Analyzer will scan a statement until the 
element (s> is found* (If the element is not in square 
bracketst the whole statement fails if the very next 
character or string fails the test of the next element*) 
This test will reject the statement if it can't find the 
element anywhere in the statement* If it succeeds* it will 
leave the marker for the next test just after the string 
satisfying the contents of the square brackets* 

"start" means check to see if the next five characters 

are: start* 

C"start"3 means scan until it finds the string: star 

t. 

C3D3 means scan until it finds three digits* 

r 3D ♦:3 means scan until it finds three digits 

followed by a colon 
-- negation 

If an element is preceded by a minus sign -♦ the statement 
will pass that test if the element does not occur* 
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-LD flieans anything other than a letter or dlgitt such 
as punctuationt Invlsiblest etc* 
NOT — negation 

NOT will be TRUE If the element or group of elements 
enclosed In parentheses following the NOT 1s false» 

NOT LD will pass If the next character Is neither a 
letter nor a digit. 
Cofliblning Elefiients 

You may put together any nusiber of any of these elements to 
forsff a pattern. They may be combined In any order. Spaces 
within the pattern are Ignored (except In literal strings) so 
they tiay be used to roake reading easier for you. 
e.g. 1$PT C«.MLS;» 1SD3 -SP 

I.e. one or more printing characters* then scan for .NLS I 
followed by one or iRore dlgltst then check that the next 
character Is not a space 
Hore sophisticated patterns can by written by using the 
Boolean logical expression features of LIO. Combinations of 
eleRsents fnay In turn be treated as single eleiBentst to be 
modified or combined using logical operators. 
Generally* an expression Is executed left to right. The 
following operations are done In the given order: 
( I 
/ 

NOT 
Af^D 
OR 
C > 

Parentheses Cand square brackets for floating scans) may be 
used to group elements. It Is good practice to use 
parenthesis liberally. 
/ 

/ means ^either or*»» the bracketed element t consisting of 
two or more alternat Ives § will be true If either (any) 
element 1s true. 

(3D L / 40) faeans either three digits and a letter or 
four digits. 
Since the slash Is executed before MOTt ^OT D / *h will be 
true 1f the next character Is NEITHER a digit nor the 
letter "h". It 1s the same as MOT CD/*h). 
SofBetlflies you may want want the scan to pass your marker 
over something If It happens to be there (an optional 
element). *»TRUE" 1s true without testing the stateifient. 
If the other tests fall* the Imaginary marker Is not moved. 
(0 / TRUE) looks for a digit and passes the Imaginary 
iBarker over It. If the next character Is not a dlgitt 
It will just go on to the next test element In the 
pattern without moving the marker and without falling 
the test. (This test always passes.) 

I.e. It Is used to scan past sofRethlng(s) which may or 
Biay not be there. 
Since expressions are executed front left to rightt It does 
no good to have TRUE as the first option. (If It Is first* 
the test will ImiBedlate ly pass without trying to scan over 
any elements.) 
AND 
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hUQ means both of the two separated groups of elements must 
be true for the statement to pass* 

SII^CE (3/6/73 00:001 Alio ID#IIDK aieans statensents 
written since March &♦ 1973 by sosReone other than NOW. 
OR 

OR iseans the test will be true If either of the separated 
elements 1s true. It does the saae thing as slasht but 
after "A^JD* and "MOT" have been executedt allowing greater 
f lexlbl llty. 

D AMD LLD OR UL means the same as CD AND LLOI OR UL 
A^D LLP / UL means the same as hm (LLD / UL) 
yhile such patterns are correct and sucdnctt 
parentheses make for much clearer patterns* ElefJients 
within parentheses are taken as a group? the group will 
be true only if the stateisent passes all the 
requl regents of the group. It Is a §ood Idea to use 
parentheses whenever there islght be any asiblgulty* 
Section 3: Examples of Content Analyzer Patterns 
2$L0 / C»CA"3 / E^Content Analyzer"! 

This pattern will watch and pass any of three types of NLS 
statements: those beginning with a numerical digit followed by 
at least two characters which may be either letters or digits? 
or statements with either of the strings "CA" or "Content 
Analyzer** anywhere In the statement* 

Mote the use of the square brackets to permit a floating 
scan -- a search for a pattern anywhere In the statement* 
Note also the use of the slash for alternatives* 
BEFORE (25-JAN-72 12:00> 

This pattern will match those statements created or modified 
before noon on 25 January 1972» 
CIO = HGL> OR CID = NOH> 

This pattern will match all statements created or ricdifled by 
users with the Identifiers "HGL" or "NDH". 
EC2L CSP/TRUE) / 20) •- 403 

This pattern will match characters In the form of phone 
nusjbers anywhere In a statement* Numbers matched isay have an 
alphabetic exchange followed by an optional space (note the 
use of the TRUE construction to accomplish this) or a 
numerical exchange* 

Examples Include DA 6-6200? DA6-6200f and 326-62 00* 
EENOCHRJ < »cba» 

This will pass those statements ending with "abc** It will go 
to the end of the stateirtentf change the scan direction to 
leftt and check for the characters "cba** Mote that since you 
are scanning backwards? to find "abc* you fRust look for "cba** 

Since the »cba" Is not enclosed In square brackets? It must 
be the very last characters In the statement* 
Section 4: Using the Content Analyzer 

Content Analyzer Patterns may be entered In two ways: 

1) From the BASE subsystem? use the command: 
Set Content (pattern) To PATTERN OK 

2) From the PROGRAHS subsystem? use the command: 
Compile Content (pattern) PATTERfl OK 

OK means "Co^imand Accept*? a control-0 or? 
In TNLS Cby default) a carriage return. 
In either case: 
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1) Patterns may be typed In frons the keyboard* or 

2) they may be text 1n a file* 

In this caset the pattern will be read from the first 
character addressed and continue until 1t finds a seinlcolon 
(f) so you ifiust put a semicolon at the end of the pattern 
tin the fllel. 
Vieyspec j must foe on C1*e« Content Analyzer off) when 
entering a pattern. 
Entering a Content Analyzer Pattern does two things: 

1) compiles a sfiiatl user prograrfi from the characters In the 

pattern* and 

21 takes that program and "Institutes* It as the current 

Content Analyzer filter program* delnsti tut Ing any previous 

pattern* 

"Instituting* a prograis aieans selecting It as the one to 

take effect when the Content knalyzer Is turned cn« You 

may have siore than one program compiled but only one 

Instituted. 

yhen a pattern Is delnsti tuted* It still exists In your 

program buffer space and may be Instituted again at any 

time with the command 1n the PROGRAMS subsystem: 

Institute Program PR0GRAH-f4AHE Cas> Content < analyzer) 
OK 

The programs niay be ref ered to by nuieber Instead of 
name* They are numbered sequentially* the first 
entered being number 1» 
All the programs you have coinplled and the one you have 
instituted may be listed with the cofBmand In the PROGRAMS 
subsystem: 

Show Status Cof prograais buffer) OK 
Prograsis may build up In your program buffer* Tc clear the 
program buffer* use the PROGRAMS subsystem cofRwand I 
Delete All Cprograiss In bufferJ OK 

ye recofBiaend that you do this before each new pattern* 
unless you specifically want to preserve previous 
patterns* 
To Invoke the Content Analyzer: 

yhen views pec 1 Is on* the Instituted Content Analyzer progran 
(If any) will check every statement before It Is printed for 
displayed)* 

If a statement does not pass all of the requi restents of the 
Content Analyzer program* It will not be printed* 

In DNLS* If no statements from the top of the screen 
onward through the file pass the Content Analyzer 
filter* the word "Empty" will be displayed* 
Note: You will not see the normal structure since one 
statement may pass the Content Analyzer although Its source 
does not* Viewspec m (statement numbers on) will help you 
determine the position of the statement In the file* 
When viewspec k Is on* the Instituted Content Analyzer filter 
will check until It finds one statement that passes the 
requirements of the pattern* Then* the rest of the output 
(branch* plex* display screen* etc*) will be printed without 
checking the Content Analyzer* 

yhen viewspec j Is on* no Content Analyzer searching Is done* 
This Is the default state* every statement In the output 
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Cbrancht plex* display screent ete*l will be printed* Note 
that If jf and k are jRutually exclusive. 
Notes on the use of Content Analyzer flltersi 

Sorfie MLS coififfiands are always affected by the current viewspecs 
Cinctudlng itjt or kit 
Output 

JuRip Cin DMLSJ 
Print tin TNLS) 
Host ULS costmands Ignore the Content Analyzer 1n their 
editing. The folloying BASE subsystein co^ffiands offer the 
option of specifying viewspecst or **F1 Iters **f (which may turn 
on the Content Analyzer) which apply only for the purpose of 
that one cornmand and affect what stateaients the coiufp-and works 
on (only those statements which pass the filter will be 
copied* moved* etc.* structure will be adjusted) 2 
Copy 
Delete 
Hove 

Substitute 
At this point* It would be wise to practice until you become 
proficient at Content Analyzer patterns* You might begin by 
trying to use some of the patterns given In the above exaiBplest 
and then try writing a few patterns of your own» These patterns 
are both a useful f^LS tool and a basic component of ntany LIO 
prograns* Me further recoft^mend that you contact ARC via your 
architect before you begin the next part* 
Pmi two: Introduction to tlO PrograiRiRlng 
Section i: Content Analyzer Prograrss 
Introduction 

yhen you specify a Content Analyzer Pattern* the PRCGRAHS 
subsystem constructs a prografs which looks for the pattern 1n 
each statesfent and only displays the statement If the pattern 
matching succeeds* You can gain pore control and do more 
things If you build the program yourself* The prog raw will be 
used just like the simple pattern prograii and has many of the 
saise lligltat Ions* Programs are written 1n NLS just like any 
other text file* They then can be converted to executable 
code by a coaipller* This code resides (or Is loaded) In your 
programs buffer space? 1t can be Instituted as the current 
Content Analyzer filter program like a Content Analyzer 
Pattern* 
PrograiR Structure 

If you specify a Content Analyzer Pattern* NLS compiles a 
sfliall program that Looks like this (with the word "pattern" 
standing for whatever you typed 1n>: 
PR06RAH name 

(name) PROCEDURE? 

IF FIWD pattern THEN RETURNCTRUE) ELSE iETtRN( FALSE ) ? 

FINISH 
LIO programs must begin with a header statefflent* the word 
PROGRAH Call caps) followed by the name of the first procedure 
to be executed Call Lower-case)* This name Is also the name 
of the prograin* If the program 1s being conplled Into a file 
(to be described at the end of this section)* the word FILE 
should be substituted for the word PROGRAH* E*g* 
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PROGRAH first 

or 
FILE deldlr 
CMote: the Content Analyzer cowpller makes up a prograui 
name consisting of UP#!xxxxXf where 

# 1s a sequential number t the first pattern being 

number onet an6 

xxxxx Is the first five characters of your pattern. > 

E.g. UP1!$LDEP 
The body of a program consists of a series of DECLARATION 
statements and PROCEDURES tin any order) which are blocks of 
Instructions. In the above case« the program consisted of 
only one small procedure and no declarations, yhen the 
program Is loaded Into your programs buffer space* the 
declarations reserve space In the systeii! to store Information 
(variables), yhen the program Is used as a Content Analyzer 
filter program* the first procedure Is called for each 
statement. It may In turn call other procedures and access 
variables In the program or In the NLS system. E.g. 
DECLARE x» yt 2 » Cdescrlbed below) 
(first) PROCEDURE t 
... 
The end of the program 1s delimited by the word "FINISH" (In 
all upper case). The compiler stops at that point* so any 
text after that In the NLS source file will be Ignored. 
Comments may be enclosed In percent signs C%) anywhere In the 
program* even In the middle of LIO statements. The LIO 
compiler will Ignore them. 

Except w1th1n literal strings* variable names and special LIO 
words* spaces are Ignored* It 1s good practice to use them 
liberally so that your program will be easy to read. Also* 
ULS file structure Is Ignored; statements will be read 
sequentially* regardless of their level. Structure Is* 
however* very valuable In making the program readable* and 1t 
Is good practice to use It In close correlation to the 
program's logical structure. For Instance* the programmer 
usually makes each of the elements of a program (declarations* 
procedures* and FINISH) separate statements* below the header 
statement 1n file structure. This point will be discussed 
further later. 

So far* we have file which looks something like: 
PROGRAH namel 

DECLARE ... ; 

DECLARE ... ; 

(namel) PROCEDURE I 

(name2) PROCEDURE 5 

FINISH 
Procedure Structure 

Each procedure must begin with Its header statement. This 
header statement Is a name enclosed In parentheses followed by 
the word PROCEDURE* and terminated by a semicolon. E.g. 

(name) PROCEDURE I 
The body of the procedure may consist of Local declarations* 
then LIO statements. An LIO statement Is any program 
Instruction* terminated by a semicolon. The body must at some 
point return control to the procedure that called It. All 
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this will be further discussed later. 
The procedure must end with the terinifiat statement: 
END. 
Example (the actual HO statefnents In this exaiiple will becoaie 
clear as you read on): 

PROGRAH cofspare % Content analyzer. Displays statement 1f 

first two vislbles are the same. % 

Ireserve space for (»declare**l four text pointers nasied 
"ptl" through '•pt4*% 

DECLARE TEXT POINTER ptl» pt2f pt3t pt4; 
%reserve 100 characters of space for each of two string 
variables named *»v1sl« and "v1s2*t% 

DECLARE STRING vlsltlOOl* v1s2El003; 
Ccompare) PROCEDURE I 

%ii find two vislbles* set pointers around first two 
vislbles Cstrlngs of printing characters)! 

IF FIND $MP '*ptl 1$PT '^pta tup >t3 ISPT '*pt4 THEM 
8EGIM 

%put vislbles 1n strings! 
*v1sl* _ pti pt2 I 
*v1s2* _ pt3 pt4 ♦ 
%coiRpare contents of strlngst return and display 
the statement If 1dent1cal% 

IF *v1sl* = *v1s2* THEN RETURNITRUE> ; 

end; 

%otherw1set return and don*t d1splay% 

RETURN (FALSE J I 
END. 
FINISH 
Declaration Statements 

As you way have guessed from the above exarfiplet Content 
Analyzer prograiss can manipulate variables (like text pointers 
and strings )t while patterns cannot. 
Text Pointers 

A text pointer points to a particular location within an 
NLS statement Cor Into a string* as described later) • 
The text pointer points between two characters In a 
statejnent. By putting the pointers between characters ♦ 
a single pointer can be used to mark both the end of one 
string and the beginning of the string starting with the 
next character. 
Text pointers are declared with the following Declaration 
statement: 

DECLARE TEXT POINTER name I 
Strings 

String variables hold text. When they are declared* the 
maximum number of characters Is set. 
To declare a string: 

DECLARE STRING nameCnuml 5 

num Is the maximum number of characters allowed for the 
string. 
E.g. 

DECLARE STRING 1st r1 ngC 1003; 

declares a string named "Istrlng* with a maxluum length 
of 100 characters and a current length of characters 
<1t»s empty!. 
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You can refer to the contents of a string variable by 
surrounding the name with asterisks. E»g« 

*lstr1ng* Is the string stored 1n the variable naiited 
^Istrlnf". 

(Refering to Istrlng without the asterisks represents 
only the first coisputer word of the string* This Is 
rarely needed*) 
You can put the text between two text pointers In a string 
variable with the LIO statements 
* I string* _ ptrl ptr2 » 

where ptrl and ptr2 are the names of previously declared 
and set text polnterst and Istrlng Is a previously 
declared string variable. 
These variables will retain their value from one statement to 
the next* Other types of variables and their use will be 
discussed In detail In Part Three* Section 3» 
Body of the Procedure 
RETUR?^ Statement 

Mo matter what It does* every procedure must return control 
to the procedure that called It* The statement which does 
this Is the RETURN statement* E*g* 

RETURN ; 
A RETURM statement may pass values to the procedure that 
called It* The values must be enclosed In parentheses 
after the word RETURN* E*g* 

RETURfl <lf23*47) ; 
A Content Analyzer prograsi iBust return either a value of 
TRUE or of FALSE* If It returns the value TRUE Ult the 
state?5ent will be printed! If It returns FALSE (0)» the 
stateisent will not be printed* I*e* 

RETURJ^ (TRUE) I will print the statetient 
RETURU CFALSE)! will not print the statement 
The RETURN statement often Is at the end of a prcceduret 
but It need not be* For exaaiplet In the »1ddle of the 
procedure you may want to either RETURN or go on depending 
on the result of a test* 
Other than the requirement of a RETURN statement t the body of 
the procedure Is entirely a function of the purpose of the 
procedure* A few of the many possible state»ents will be 
described here; others will be Introduced In Part Three of 
this docuiBent* 
FIMD Statement 

One of the jRost useful statements for Content Analyzer 
programs Is the FIND statement* The FIND statement 
specifies a Content Analyzer pattern to be tested against 
the statesientf and text pointers to be manipulated and sett 
starting from the Current Character Position (that 
Invisible marker refered to In Section D* If the test 
succeedsf the character position Is moved past the last 
character read» If at any point the test falls* the 
character position Is left at the position prior to the 
Flf^O stateuent* The values of text pointers set 1n the 
statesient prior to the falling element will reaa 1n as set* 
others of course will not be changed* 

FIMD pattern I 
The Current Character Position 1s Initialized to BEFORE THE 
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FIRST CHAf^ACTERf and the scan direction Is Initialized to 
Left to RIGHTf FOR EACH HEU STATEHENT passed to the Content 
Analyzer prograRi* 

Any simple Content Analyzer pattern (as describe above) Is 
valid in a FIND statement* 

In addltlont the following elements can be Incorporated in 
the pattern! 
♦stringnane* 

the contents of the string variable 
*ptr 

store current scan position Into the text pointer 
specified by ptrt the naiRe of a declared text pointer 
_f^ UH p t r 

back up the specified text pointer by the specified 
nuBiber CNUMJ of characters* If HUPi Is not specified* 
1 will be assuiied* Backup is in the direction 
opposite to the current scan direction, 
pt r 

Set current character position to this position* ptr 
Is the name of a previously set text pointer. 
SFCptr) 

The Current Character Position Is set to the front of 
the stateisent In which the text pointer ptr Is set 
and scan direction is set froifj left to right. 
SECptri 

The Current Character Position Is set to the en6 of 
the statement In which the text pointer ptr Is set 
and scan direction is set frofn right to left. 
BEiyEEf^ ptrl ptr2 (pattern) 

Search llailted to between positions specified. ptr 
is a previously set text pointer; the two pust be in 
the saiae stateirtent or string. Current Character 
Position is set to first position before the pattern 
is tested. E.g. 

BETyEEN ptl pt2 (20 C.3 $NP> 
FINDS may be used as expressions as well as free-standing 
Stat eiients* If used as an expression* for exapple In IF 
stateiBentst it has the value TRUE if all pattern elements 
within it are true and the value FALSE If any one of the 
elements Is false. E.g. 

IF FIND pattern THEN ... i 
CoiRplicated example: 

IF FIMD '"sf $NP •( $(LD/»-) •> C". •• *str*I SC€sf) $NP 
•. THEM RETURM(TRUE) ELSE RETURN( FALSE) ? 
IF Statement 

IF causes execution of a stateittent if a tested expression 
Is TRUE. If It is FALSE and the optional ELSE part Is 
present* the stateiRent following the ELSE is executed. 
Control then passes to the statement liRinedlately following 
the IF statewent. 

IF testexp THEN statement ♦ 

IF testexp THEM statementl ELSE state«^ent2 ; 
The statefsents within the IF statement can be any valid LIO 
statementt but are not followed by the usual seailcolonl the 
whole IF statement is one LIO statement and is followed by 
a semicolon. 
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IF FIND C5D3 THEf^ RETURPICFALSE > ELSE RETURN CTRUE) I 
Prograriiting Style: File Structure 

The cofupiler which converts your MtS text to code ignores l^LS 
file structure. This allows you to use structure tc isake your 
program text easier to read and understand* Logical use of 
structure often facilitates the actual programming task as 
well* Some conventions have developed at ARC in this respect* 
although flexibility is essential* These should seem obvious 
and logical to you* 

All declarations and PROCEDURE stateisents should be one 
level below the PROGRAH statement* 

All local declarations tnot yet described) and cede should 
be one level below the PROCEDURE stateaient* 

It is good style* and stakes for much easier prog raafiBiingt to 
list what you want to do as cofuwent statements C in percent 
signs) at the level below the PROCEDURE statement* Then 
you can go back and fill in the code that accowp lishes the 
task described in each comsient statement* The code should 
go one level below the coaiiRent* 

It is also worthwhile to put co^sients In individual 
statements whose purpose is not obvious* 

ye will later describe how to block a series of statenients 
where one is required* These blocks should go a level 
below the statetnent of which they are a part* 
File structure should follow the logical structure of the 
prograro as closely as possible* E*g* 
IF FIND C5D3 

THEM RETURMCTRUE) 
ELSE RETURN(FALSE); 
Using Content Analyzer Programs 

Once the Content Analyzer prograsi has been written (in an NLS 
file)f there are two steps in using it* First* the program 
Biust be "coiBpiledf" i*e* translated into machine-readable 
code* the compiled code is "loaded" into a space reserved for 
user programs (the user programs buffer)* Secondly* the 
loaded program must be •'instituted* as the current Content 
Analyzer programm 
There are two ways to compile and load a program: 

1) You may compile a program and load it into your programs 
buffer all in one operation* In this case* the program 
header statement must have the word PROGRAH in it* When 
the user resets his job or logs off* the compiled code will 
disappear* 

First* enter the Programs subsystem with the command: 

Goto Programs OK 
Then you may compile the program with the comtand: 

Compile LIO (user program at) SOURCE OK 

SOURCE is the f4LS file address of the PROGRAH 

statement* 

2) You may compile a program into a TENEX code file and 
then load it into your buffer in a separate operation* The 
program can then be loaded from the file into your user 
programs buffer at any time without recompiling* The 
header statement must use the word FILE instead of PROGRAH* 

Use the PROSRAHS subsystem command: 
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Compile File Cat) SOURCE {ys1ng> LIO Cto f1Le> FILEMAHE 
OK 

The FILENAHE «ust be the same as the prograsi^s na^e* 
The code file Is called a REL (RELocatable code) file. 
Whenever you wish to load the ppograis code Into the user 
programs buffert use the PROGRAMS subsysten ccmiiand: 
Load Prograsi Cfile) FILENAME OK 
Once a compiled program has been loaded (by either route)f It 
must be Instituted* This Is done with the PROGRAMS subsystets 
coifiiBand: 

Institute Program PROGRAH-NAHE (as) Content (analyzer 
prograst) OK 

The nafsed program will be Instituted as the current Content 
Analyzer flltert and any previously Instituted prograRi will 
be delnstltuted (but will remain In the buffer)* 
Again* the programs In the buffer are nufsbered* the first 
In being nusrber one* You fnay use the nufnber Instead of the 
program*s name as a shorthand for PR06RAH-NAHE, 
To Invoke the Content Analyzer using whatever program Is 
currently Instituted* use the viewspec 1» }♦ or kt es 
described In Part One* Section 4 i3dA), 
Problems 

Given these few constructs t you should now be able to write a 
nuaber of useful Content Analyzer prograns* Try prcgraiminc 
the following: 

1) Show those statements which have a nusiber somewhere In 
the first 20 characters* 

2) Show those state»ents where the first visible In the 
statement Is repeated sofnewhere In the statefsent* 

Sample solutions: 
Probleffi 1 

PROGRAM number 

DECLARE TEXT POIRITER ptrl* ptr2 ? 
(number) PROCEDURE I 

FIMO ''ptrl S20CH "ptr2 » 
IF FIND BETk'EEM ptrl ptr2 ( CD3 ) 
THEr^ RETURN(TRUE) 
ELSE RETURf4(FALSE)f 
END . 
Flf^ISH 
Alternate Solution to Problem i: Content Analyzer Filter 

$20CH < CD3 
Problem 2 

PROGRAH vis 

DECLARE TEXT POINTER ptrlt ptr2 I 
DECLARE STRING strESOOl ; 
(v1s) PROCEDURE ; 

FIND $NP *ptrl ISPT '"ptr2 ; 
*str* _ ptrl ptr2 ; 
IF FIND ptr2 E NP *str* UPl 
THEN RETURN (TRUE) 
ELSE RETURN(FALSE) ; 
END. 
FINISH 
Section 2: Content Analyzer Programs: Kodlfying Statesients 
Introduction 
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Content Analyzer prograws «ay edit the statements as yell as 
decide whether or not they are printed. They are very useful 
where a series of editing operations has to be done tiBie and 
time again* This section will Introduce you to these 
capabilities* All these constructs will be covered in detail 
In Part Three* 

A Content Analyzer progrars has several limitations* It can 
manipulate only one file and It can look at stateserts only in 
sequential order Cas they appear In the fllel* It cannot back 
up and re-exaffl1ne previous statementst nor can It skip ahead 
to other parts of the file* It cannot Interact with the user* 
Part Four provides the tools to overcome these limitations* 
String Construction 

Statements and the contents of string variables may be 
modified by either of the following two statements: 
ST ptr _ strlngllst ♦ 

The whole statement In which the text pointer named 
"ptr** resides will be replaced by the string list Cto be 
described In a ailnute)* 
ST ptr ptr _ strlngllst * 

The part of the statement froiR the first ptr to the 
second ptr will be replaced by the string list* 
ptr may be a previously set text pointer or SF<ptr> or 
SECptrJ* 
The content of string variables may be replaced with the 
string assignment stateiient: 

*str ingname* _ strlngllst * 
The string list Cstrln^llst) roay be any series of string 
deslgnatorst separated by coffinias* The string designators may 
be any of the following (other possibilities to be described 
later>2 

a string constant* e*Q* *»ABC" or 'w 
ptr ptr 

the text between two text pointers previously set In 
either a statement or a string 
*str Ingname* 

a string name In asterisks* referlng to the contents of 
the string 
E * g • I 

ST pi p2 _ * string* » 

or 
ST pi _ SFCplJ pit *str1ng*» p2 SECp2); 

CNote: these have exactly the saroe meaning* > 
Exaatple: 

PROGRAM delsp % Content analyzer. Deletes all leading 
spaces frofa statements* % 

%reserve space for ("declare") a text pointer named "pt**% 

DECLARE TEXT POINTER pt? 
CdelspJ PROCEDURE ; 

%1f any leading spaces* scan past theiR and set pointer! 
IF flHQ 1$SP ''pt THEN 

Sreplace statement with text froiR pointer to 
statersent end% 

ST pt _ pt SE(ptl? 
%returnt don*t display anyth1ng% 
RETURM CFALSEJ ; 
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END. 
FIiyiSH 

Hore Than One Change per Stateiiient 

Part of a text pointer Is a character count. This count stays 
the saRie until the text pointer Is again set (to soie other 
pos1t1on>i even though the statement has been editec. Ift for 
examplei you have the statement 

abcdefg 
and If you have set a pointer between the "d* and the "e^t 1t 
5rfHL always point between the fourth and fifth characters 1n 
the statetnent. If you then delete the character *»a*f your 
pointer will be between the *e* and the *f »* t now the fourth 
an6 fifth characters* For this reasont you should begin a 
series of edits with the last one In the statement and work 
backwards through the stateinent* 

Controlling yh1ch State»ents are Modified 

In TNLSt the Content Analyzer program will be called for 
coiiifiiands which construct a printout of the file Cprint and 
Output). The prograifs will run on every statement for which It 
Is called (e«g» e\tery statefiient 1n the branch during a Print 
Branch command) which pass all the other viewspecs* Once you 
have wrlttent complledt and Instituted a program which does 
sofRe editing operationt the Print coinRiand Is the easiest way 
to run the program on a statement* branch* plext or group* 
In Df^LS* the system will call the Content Analyzer program 
whenever the display is recreated Ce.g* viewspec F and the 
4urf!p commands)* and also for the Output comsiands. If the 
program returns TRUE* it will only run on enough statements to 
fill the screen* It is safer to have programs that edit the 
file return FALSE. Then when you set viewspec 1* it will run 
on all statements from the top of the display on* and when it 
is done it will display the word "Empty** At that point* 
change to viewspec j and recreate the display with viewspec F* 
then all statements including the changes will be displayed* 
You can control which statements are edited with level 
viewspecs an6 the branch only (g> or plex only (I) viewspecs* 
and by positioning the top of your window* 
After having run your program on a file* you may wish to 
Update to permanently incorporate the changes in the file* It 
is wise to Update before you run the program so that* if the 
program does something unexpected* you can Delete 
Modifications and return to a good file* 

Problems 

Try writing the following programs! 

1) Remove any invisibles from the end of each statement* 

2) M.&ke the first word a statement name surrounded by 
parentheses* 

Sample solutions: 
Problem 1 

PaOGRAH endinv 

DECLARE TEXT POINTER ptr » 
lendinv) PROCEDURE * 

IF FIND '^ptr SE(ptr) 1%HP '*ptr 
THEN ST ptr _ SFCptr) ptr ; 
RETURN CFALSEI 7 
EMD* 
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P rob I em 2 

PROGRAH fBakename 

DECLARE TEXT POINTER ptrlt ptr2 ; 
CmakenanteJ PROCEDURE ; 

IF FIND $HP '^ptrl 1$L0 '"ptr2 

THEN ST ptrl _ ^Ct ptrl ptr2t •># pt r2 
SECptr2>; 
RETURNCFALSEJ 
END. 
FINISH 
PART THREE: Basic LIO PrograiBBilfig 

Section 11 The User Program Environment 
Introduction 

User-written Content Analyzer prograiss are called 1n the 
process of creating a view of an HLS file e«g.» with a Print 
coronand In TMLSt with any of the Output cosfliandst and with the 
Juisp coasaand In DI<ILS» 

The sequence generator provides statements one at a tlpel 
the Content Analyzer laay then check each one» Final lyt the 
formatter prints It or puts 1t on the screen* 
Thus If one had a user Content Analyzer prograis compiled 
and Instltutedf one could have a printout made containing 
only those statefnents In the file satisfying the pattern. 
Attachable subsysteats are independent of this portrayal 
processt although they are welcome to siake use of it* They 
consist of cofflmandsf which inay utilize all the powers of NLS» 
The Sequence Generator 

In the portrayal process* the sequence generator looks at 
statements one at a tiae* beginning at the point specified by 
the user* It observes viewspecs like level truncation in 
deterroining which statesients to pass on to the formatter, 
yhen the sequence generator finds a statement that passes all 
the viewspec requirementsi it sends the statement tc the 
forinatter and waits to be called again for the next statesient 
in the sequence. 

For examplet the viewspecs may indicate that only the first 
line of statements in the two highest levels are to be 
output. The default MLS sequence generator will produce 
pointers only to those stateiRents passing the structural 
filters! the formatter will then truncate the text to only 
the first line before It displays or prints the stateeient. 
Content Analyzer Filters 

One of the Viewspecs that the sequence generator pays 
attention to is *i* — the viewspec that indicates whether a 
user Content Analyzer filter is to be applied to the 
statement. If this viewspec is ont the sequence generator 
passes control to a user Content Analyzer program* which looks 
at the statement and decides whether it should be included in 
the sequence. If the statement passes the Content Analyzer 
C1#e. the user program returns a value of TRUE)* the sequence 
generator sends the statement to the formatter; otherwise* it 
processes the next statement In the sequence and sends it to 
the user Content Analyzer program for verification. CThe 
particular user program chosen as a filter is deteririned by 
what program is Instituted as the current Content Analyzer 
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prografRf as described below. > 

In the process of examining a stateaient and deciding 
whether or not It should be prlntedt the Content Analyzer 
prograiR may edit the text of the statement* These edits 
appear In the partial copy* just as If the user had made 
them himself* This provides a powerful ntechanlsRi for 
auto?Rat1c editing. 

In ONLSt If you display any statement st the prograst will 
stop after filling the screen* If you are not displaying 
any statefsentst the prograat will run on either the whole 
filet a p lex (viewspec Dt or a branch Cvlewspec g> • These 
along with level clipping viewspecs give one precise 
control over what statements In the file will be passed to 
the program* 
The Portrayal Formatter 

The formatter arranges text passed to It by the sequence 
generator In the style specified by other viewspecs* The 
formatter observes viewspecs such as line truncal Ion t length 
and Indenting; It also formats the text in accord with the 
requirements of the output device* 
Section 2: Program Structure 

An NLS user prografs consists of the following eleiientst which 
must be arranged In a definite manner with strict adherence to 
syntactic punctuation: 
The header - 

a statement consisting of the word PROGRAM* followed by the 
name of a procedure In the prograoi* Program execution will 
begin with a call to the procedure with this name* 
PROGRAH name 

The PROGRAM stateiBent may have a statement naise In 
parentheses; It will be Ignored* 
The word FItE should be substituted for the word PROGRAM If 
the code Is to be compiled Into a file to be saved* 

The FILE statement may have a statement name; If sot 
that name will be used as the code*f1le symbol* You 
must not follow the word FILE with a name If there Is a 
statement name preceding FILE* 
The body - 

consists of declarations and procedures In any order! 
1> declaration statements which specify Information 
about the data to be processed by the procedures In the 
program and enter the data Identifiers In the program^s 
symbol tablet terminated by a semicolon* E*g* 
DECLARE x»y»2 » 
DECLARE STRING testtSOOl ; 
REF x» Zt 

Declaration statements will be covered In Section 3 
(5c >* 
2) procedures which specify certain execution tasks* 
Each procedure must consist of: 

the procedure name enclosed In parentheses followed 
by the word PROCEDURE and optionally an argument list 
containing names of variables that are passed by the 
calling procedure for referencing within the called 
procedure* This statement must be terminated by a 
semicolon* E*g* 
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CnafEeJ PROCEDURE » 

Cnase) PROCEDURE (paraBil* paraai2J I 
You shoyld always include a coiaiBent in the 
procedure statement brelflysuwajarlzlng the 
function of the procedure* 
the body of the procedure which maty consist of LOCALt 
REFt and LIO statements. 

LOCAL and REF declarations within a procedure must 
precede executable code. They will be covered in 
Section 3 C5c). 

LIO stateroents will be covered in Sections ^ and 5 
(5d> (5e). 

A RETURN statement wust be included at so»e 
pointf to pass control back to the calling 
procedure. If it is missingt execution will 
run off the end of the procedure and an ILLEGAL 
INSTRUCTION will occur, 
the stateirtent that teraiinates the procedure Cnote the 
final period): 
EUD. 
The prograw terisinal statement - 
FIfslISH 

Wote: this is a signal to the coinpiler to step 
coiRpilationl it does not mean stop execution. kny text 
after that in the I^LS source file will be ignored. 
liotes on Prograsi Writing Style 

Except for within literal strings t variable naaieSf and special 
LIO reserved words* spaces are ignored. It is good practice 
to use theRi liberally so that your program will be easy to 
read. 

Coffiwents may be enclosed in percent signs C%> wherever spaces 
are allowed. They will be ignored by the compiler. It is 
good practice to use the level below the procedure stateaient 
for cofBBientst filling in the code that executes the cofRjRented 
function at the level below the coRiwent. It is also wise to 
add cowfflents to any individual stateffients whose function is 
not obvious* particularly calls on other procedures. 

You may find it convenient to add a coiafii en t to the FILE 
stateitent including the information needed by the Co siip He 
File coiBffiand. E.g. 

FILE prograsi % CLlOtl to (directorytprograit.subsy st ) % 
Also* NLS file structure is ignored. Structure is* however* 
very valuable in waking the prograai readable* and i t is good 
practice to use it in close correlation to the program's 
logical structure. 
An exafsple of a simple LIO program is provided here. The reader 
should easily understand this program after having studied this 
docufsent. 

PROGRAH delsp % Content analyzer. Deletes all leading 

spaces from statements. % 

Xreserve space for <"declare'*l a text pointer named "pt"% 

DECLARE TEXT POINTER ptl 
Cdelsp) PROCEDURE ; 

%1f any leading spaces* scan past them and set pointer! 
IF FIND ISSP '^pt THEN 

^replace statement holding pt with text from 
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pointer to statement end! 
ST pt ^ pt SEIptH 
%return» don»t d1splay% 

RETURN (FALSE) 5 
END. 
Flt^ISH 
Section 3: Declarations 
Introduction 

LIO declarations provide Infonnatlon to the compiler aboyt the 
data that Is to be accessed* they are not executed. Every 
variable used In the program must be declared somewhere In the 
system (either In your program or In the NLS systesl. 
There are a number of types of variables avallablet each with 
Its own declaration statement; the most frequently used are 
discussed here. CComplete documentation Is available In the 
LIO Reference Guide -- 7052f) 
Variables 

Six types of variables are described In this docuiBent: slmplet 
constants* arrayst text pointers* strlngst and referenced. 
Each Is represented by an Identifier* some unique lowercase 
name. Each can foe declared on three levels t local* global* or 
external. 
Local Variables 

A local variable Is known and accessible only to the 
procedure in «h1ch It appears. Local variables jrust appear 
In a procedure argument list or be declared In a 
procedure's LOCAL declaration statefRents (to be explained 
below). kny LOCAL declarations must precede the executable 
statements 1n a procedure. 

Local variables In the different procedures may have the 
same name without conflict. A global variable may not be 
declared as a local variable and a procedure name may be 
used as neither. In such cases the name Is considered to 
be multiply defined and a compilation error results. 
Global Variables 

Global variables are defined In the program's DECLARE 
statements. Variables specified In these declarations are 
outside any procedure and may be used by all procedures In 
the program. 
External Variables 

External variables are defined In the program's DECLARE 
statements or In the MLS system program. 

Variables specified In these declarations may be used by 
all procedures anywhere In the system. Many externals are 
defined as part of the MLS system? user programs have 
complete access to these. Since other procedures may 
access the same variable* the user programmer must be very 
careful about changino their values. 
Simple Variables 

Simple variables represent one computer word* or 36 bits* of 
memory. Each bit Is either on or off* allowing binary numbers 
to be stored In words. Each word can hold up to five ASCII 
T'-bIt characters* a single number* or may be divided Into 
fields and hold more than one number. 

Declaring a variable allocates a word In the computer to 
hold the contents of the variable. The variable name 
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refers to the contents of that word* One aiay refer to the 
address of that cofnputer word by preceding the variable 
nape by a dollar sign ($>. 

For examplet If one has declared a slupie variable 
called "nuffl^f one stay put the number three In that 
variable with the stateiiient: 

V\U9 3 f 

One may add two to a variable with the statement: 
num _ num + 2 * 

One may put the address of num Into a variable called 

addr with the statement: 
addr _ $num ; 
One may refer to predefined fields In any variable by 
following the name of the variable with a period* then the 
field najf*e. For example* the fields RM and LH are globally 
defined to be the right and left half (18 bitsi of the word 
respectively! e»g. 

nyis»LH ^21 

nuiR.RH _ 3 ; 
Fields may be defined by the user with RECORD statements 
(described In Section 5 of Part F1ve)» Addltionallyt you 
stay refer to system-defined fields Ce*8» UN)* They divide 
words Into fields by numbers of b1ts» so they fia y refer to 
any declared word» For example* the field »LH" refers to 
the left-most 18 bits In any 56-b1t word* 

If you assign a full word to a field of n bits within a 

word* the rlght-inost n bits will be assigned to the 

field In the destination wordl the rest of the 

destination word will be untouched. 

If you assign a field with a word to a full wcrd* 1t 

will be r Ight- just1 f led within the destination word; the 

remaining bits In the destination word (to the left of 

the assigned bits) will be set to zero* 
Declaring Simple Global Variables 
DECLARE name i 

"nape" Is the nafse of the variable* It must be all 

lowei — case letters or digits* and must begin with a 

letter* 
E*g* 

DECLARE xl i 
Optionally* the user isay specify the Initial value of the 
variable being declared* If a simple variable Is not 
Initialized at the program level* for safety It should be 
Initialized In the first executed procedure In which It 
appears* 

DECLARE name = exp » 

exp Is the Initial value of naroe* It may be any of the 

following: 

- a nusieric constant optionally preceded by a islnus 
sign (-) 

- a string* up to five characters* enclosed In 
quotation marks 

- another variable name previously defined In a SET 
statement (described belowJ* causing the tatter's 
value to be assigned 

Examples: 
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DECLARE x2=5; 

%x2 contains the value 5% 
DECLARE X3="0UT«; 

1x3 contains the yord OUT% 
DECLARE xx=x4; 

%x4 has previously been declared in a SET 
statei«ent% 
Foriial parameters (passed to a procedure? are allocated as 
local slffiple variablest then initialized whenever the 
procedure is called* Within the called proceduret they should 
be treated as simple variables. 
Constants 

You laay declare a (simple) variable to be a constant value 
with the statement: 
SET naBiel=exp * 

where names and expressions are as described above for 
initializing simple variables* 
Constants take no memory* They may be refered to just like 
siiiple variables* except the name must be preceded by a dollar 
sign ($)• They may not be changed by the program* E»g» 
after the declaration: 

SET var = 4 ; 
the assigniRent: 
nufli _ $'^ar 5 
will assign the value 4 to the variable numm 
Arrays 

Hulti-word cone-dimensionelJ array variables siay be declared* 
coisputer words within theit may be accessed by indexing the 
variable naBie» The index follows the variable name 9 and is 
enclosed in square brackets C 3» The first word of the array 
need not be indexed* The index of the first word is zerot so 
if we have declared a ten element array named "blah*: 
blah is the first word of the array 
blahC13 is the second word of the array 
blahC93 is the last word of the array 
Declaring Global krray Variables 
DECLARE naiRernufBl t 

num is the number of eleisents in the array if the array 
is not being initialized. It ffiustt of courset be an 
integer* 
E*9* 

DECLARE samClOll 

declares an array naaied "saai" containing 10 etewents* 
Optionallyt the user may specify the initial value of each 
element of the array m If array values are not initialized 
at the program level* for safety they should be Initialized 
in the first executed procedure in which the array is used* 
DECLARE name = (nu^ilir num2» *** I * 

num is the initial value of each element of the 
array* The number of constants iiBplicitly defines 
the nuanber of elements In the array* They may be any 
of the constants allowed for sis^ple variables* 
Note: there is a one-to-one correspondence between the 
first constant and the first elefsent* the second 
constant and the second eleaientt etc* 
Exaffiples: 
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DECLARE rtuiRbs=(l»2t3); 

declares an array named nussbs contalnlns 3 
etestents which are initialized such that: 
nuibs = 1 
nuRibsCll = 2 
nyfl»bsC2 3 = 3 
DECLARE fBOtley = C10f Sblah )♦ 

declares an array naiaed motley containing 2 
elements which are Initialized such that: 
motley = 10 

»otleyC13 = Sblah = the address of the variable 
«blah« 
Text Pointers 

A text pointer 1s an LIO feature used in string manipulation 
constructions* It Is a two-word entity which provides 
Inforraation for pointing to particular locations within textt 
whether in string variables or in NLS stateroents. 

The text pointer points between two characters in a 
statement or string. By putting the pointers between 
characters a single pointer can be used to mark both the 
end of one substring and the beginning of the substring 
starting with the next charactert thereby simplifying the 
string isanlpulat ion algorithms and the way one thinks about 
strings* 
A text pointer consists of two words: a string identifier and 
a character count* Assume you have declared a text pointer 
named "pt." 

pt refers to the first word of the text pointer* The first 
wordf called an *stidt" contains three system-defined 
fields: 

stflle — the file number lit an f^LS statement) 

stastr — a bit indicating stringt not an WLS statement 

stpsid — the psid of the stateiRentl every st ateiient has 

a unique number (psid) attached to it* 

The stid Is the basic handle on a statement In LIO* It 

is often used alone. Since it is a single-word valuet 

it may be stored In a slfRple variable and passed easily 

between procedures* and is used by many routines to 

specify a statement or string* 

If an stid Is used without being properly set« the 
run-time error message *»fst entry nonexistant* may 
result • 
ptC13 refers to the second word of the text pointer* The 
second word contains a character countt with the first 
position being 1 (before the first character)* 
For examplet one might have the following series of 
assignment stateiuents which fill the three fields of the 
first word and the second word with data* with pt being the 
name of a declared text pointer: 
pt. stflle _ fileno; 

%f1leno 1s 3 simple variable with a number in 1t% 
pt.stastr _ false; 

%a statement t not a string% 
pt. stpsid _ origin; 

%all origin statements have the psid = 2* origin is a 
global variable with the value 2 in 1t% 
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pt£13 _ 15 

%the word one after pt f1«e« the character countJ 
gets 1» the beginning of the stateiient% 
It Is important that st1d*s be Initialized properly to 
avoid errors. Text pointers may be most easily initialized 
by setting them In a FIWD statement fsee Section &>• 
Oeclarinq Text Pointers 

DECLARE TEXT POINTER pt 5 

The names pit p2f p3t p4f and p5 are globally declared and 
reserved for system use* 
Strings 

String variables are a series of words holding text* yhen 
they are declaredt the maxliRust nuinber of characters Is set. 
The first word contains the two globally defined fields: 

n — the iRaxifRuiB number of characters the string can hold 
L •— the actual number of characters currently in the 
string 
The next series of words (as many as are required by the 
maximum string size) hold the actual characterst five per 
wordf In ASCII 7-bit code. 

*str* refers to the contents of the string variable *»str»*» 
str refers to the first word of the string variable *str"l 
typically this Is only useful in combination with the two 
fields "M" ar\6 "L": 

str.H refers to the maximum declared length of the 
string variable »str*» tan integer). 

str.L refers to the current length of the string stored 
in the string variable "str* tan Integer) • 
Declaring Strings 

The DECLARE STRIN<7 enables the user to declare a global 
string variable by initializing the string and/or declaring 
its fBaxiiiuai character length. 
To declare a string: 

DECLARE STRING nasieEnual » 

nui! is the laaxiwufR nuaiber of characters allowed for 
the string 

Since the iBaxisiufR stateiaent length is 2000 
characterst you should not need to declare a string 
greater than 2000 characters long. 
E.g. 

DECLARE STRING Istr ingClOOl; 

declares a string named "Istrlng* with a maximuiR 
length of 100 characters and a current length of 
characters 
To declare and initialize a string: 

DECLARE STRING narse="Any string of text" ? 
The length of the literal string defines the «axi!Buif 
length of the string variable. 
E.g. 

DECLARE STRING fBessage=*RED ALERT*; 
declares the string Hiessaget with an actual and 
maxiaiust length of 9 characters and contains the text 
«RED ALERT" 
REF: Referenced Variables 
Reference Declarations 

After a sifsple variable has been declared* the R£F 
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statement can define it to represent some other variable* 
k referenced variable holds the address of another declared 
variable of any type* yhenever the referenced variable is 
mentionedf LIO will operate on the other variable instead* 
as if it were declared in that procedure and named at that 
point* 

This Is useful «hen you wish a procedure to know about a 
iBulti-*word variable* In procedure calls* you are only 
allowed to pass single-word parartieters* If you wish a 
called procedure to use or operate on a text pointer* 
arrayt or string* you may pass the address of that 
multi-word variable* Then* in the called procedure* you 
must R£f the forisal parameter receiving that address* From 
then on in the called procedure* when you refer to the 
REFed parameter* you are actually operating on the 
multi-word variable declared in some other procedure to 
which the local REFed variable points* i*e* on the variable 
at the address contained in the REFed parameter* 
EKample: 

If the sisiple variable "loc** in the current procedure 
has been REFed and contains the address of the string 
"str* local to the calling procedure* then operations 
on loc actually operate on the string in strl 
*ffies* _ *loc*» 

%f!ies gets the string in str% 
*loc* _ "corpuscle"; 

Istr gets the string «corpuscle"% 
Siifiilarly* you cannot return aiulti-word variables frosi a 
called procedure* If you wish a procedure to return a 
string* you must declare the string as a local in the 
CALLING procedure* pass its address to a REFed variable in 
the called procedure* Then the called procedure can podify 
the string as if it were local (and return nothing)* The 
modifications will be made in the actual string variable. 
Unref erencing REFed Variables 

One may refer to the actual contents Can address) of a 
REFed variable {i*e* "unref" it) by preceding the 
referenced variable nase with an ampersand CS.)* If* for 
exaiBple* an address was passed to a REFed variable* and you 
wish now to pass that address on to another procedure* you 
can "unref* it* i*e* access the actual content C the address 
of sofBe variable)* 

E*g* if X has been REFed and holds the address of y: 
z. __^ X ? 

%z gets the CONTENTS of y% 
2 _ &x 5 

%z gets the ADDRESS of y% 
This construct might be used* for example* if one procedure 
has been passed the address of a string* operates on it* 
then wishes to pass (the address of) that string on to 
another procedure that it calls* 

This can be a tricky concept? it iRay be worthwhile to 
review this section carefully* 
REFing Simple Variables 

Once a simple variable has been declared (as a global* 
local* or parameter)* it may be REFed with the LIO 
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declaration stateient: 

REP var t 
It will be a reference from then on in that procecSuret and 
you must always use the ampersand to refer to Its actual 
contents* the address of the variable It references* 

Mote that the REF statentent does not allocate storage* 
1t just sets an attribute of an existing variable* 
If you wish to use a variable that 1s not REFed as if It 
were REFedt enclose It In square brackets llm E.g. assume 
the sifBple variable "astr" holds the address of a string 
variable but was NOT REFed: 

*Castr3* refers to the contents of the string variable 
whose address Is in astr* 
lyote on Programming Style 

You should always REF locals and parameters which hold the 
address of sosiething to be accessed Ceven If that variable 
Is only used to pass the address on to another procedure). 
Declaring Hany Variables In One Statement 

One snay avoid putting several Individual declarations of 
variables In a series by putting variables of siRiilar typcf 
Initialized or nott in a list In one statement following a 
single OECLAREt separated by cosnnas an6 terssinated by the 
usual semicolon* Array and simple varlbles aiay be put 
together in one stateiRent. 
Examples: 

DECLARE x» yElOlt 2 = Clt 2f -5>; 
DECLARE TEXT POINTER tpt sft ptl» pt2 ; 
DECLARE STRING Istri ngC1003» message^ "RED ALERT" I 
Declaring Locals 

Program level declarations (DECLARE and REFJ and procedures 
may appear in any order* Howevert procedure level 
declarations (LOCAL and REF inside a procedure) must appear 
before any executable statements In the procedure* The 
different types of variables may be declared In any order* but 
a variable must be declared before 1t can be REFed* 
yhenever possible* LOCALs should be used instead of 
globals* It makes for a cleaner program if you pass 
parameters among procedures rather than depend on global 
variables to transmit Information* 
yith one exception* a local variable declaration statement 1s 
5ust the same as a global with the word "LOCAL" substituted 
for the word "DECLARE"* The one exception is that LOCAL 
declarations can not initialize the variables* 
Examples: 

LOCAL var* flag* levelC123 I 
LOCAL TEXT POINTER tp» pt* sf ; 
LOCAL STRING testClOOl* outC20003 ; 
yhen a procedure is called by another procedure* the calling 
procedure may pass one-word parameters* The procedure 
receives these values in simple local variables declared in 
the PROCEDURE statement's parameter list* For example* two 
locals will automatically be declared and set to the passed 
values whenever the procedure "procname" Is called: 
tprocname) PROCEDURE tvarl* var2) ♦ 

varl and var2 must not be declared again In a LOCAL 
statement* They may* however* be REFed by a REF statement* 
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as discussed abovet and used throughout the procedure* 

The statement which calls procnaise may look tike: 
procname Clocvart 2) » 

varl will be Initialized to the value of the variable 
"locvar* and var2 will §et the value 2. 
Declaring Externals 

Externals are declared just like globals* with one exception. 
The word DECLARE mu&t be followed by the word EXTERNAL. E*g» 

SET EXTERNAL one=lf two=2 ? 

DECLARE EXTERNAL at bC103» c~5 ; 

DECLARE EXTERNAL TEXT POIMTER exptrlt exptr2 » 

DECLARE EXTERI^AL STRING exstrCiG0 3 I 
REF specifications may not be external tc the progreiii* 
Accessing Registers 

The user may access machine registers Cthe same length as 
other words* I.e. 36 bits) by naming therr* with the 
declaration: 

REGISTER nawe = regnum » 
or 

REGISTER naaiel=regnuffil* naiBe2==regnum2 « 
The declared names will then represent the registers to which 
they are attached. You may then access or assign values to 
their content. On TENEXt the user prograEmer siay use the 
first seven registers* registers through 6. (Registers 7 
through 15 are reserved for system use.) E.g. 

REGISTER r0=9t rl^lt r2=2t rSsSt r4=4t r5=5t r6=:6 * 

The names used In the above exawple are used most often by 

convention. 
Registers must be used very carefully! They are typically 
used when calling TENEX JSYS (see Section 4). Hany LIO 
constructs and procedures use the registers? you should assign 
their content to a variable Itawedlately after the JSYS call If 
you wish to save It. 
Section 4: Stateaients 
Introduction 

This section will describe soBte of the types of statements 
with which one can build a procedure. The terra "expression* 
Coften abbreviated to "exp") will be used In this section* and 
will be explained In detail In Section 5 C5e). 
Assignment 

In the assignment statement* the expression on the right side 
of the •»_« Is evaluated and stored In the variable en the left 
side of the statement. 

var _ exp ♦ 

where var = any global* local* referenced or unreferenced 

variable. 
One may make a series of assignments In one statement by 
enclosing the list of variables and the list of expressions 1n 
parentheses. The order of evaluation of the expressions Is 
left to right. The expressions are evaluated and pressed onto 
a stack; after all are evaluated they are popped froirt the 
stack and stored In the variables. 

I varl* var2f ...) __ Cexpl* exp 2* #••) ♦ 

f^aturally* the nusuber of expressions must equal the nuBtber 

of variables. 

Example: 
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The expression c*d Is evaluated and stacked* the 
expression a-b 1s evaluated and stacked* the value of 
a-b Is popped from the stack and stored Into b* and 
flnallyt the value of c-i^d 1s popped and stored Into a. 
It Is equivalent to: 
tempi _ c+d ; 
tefnp2 _ a-b » 
b _ tesip2 ; 
a ^ t e ffip 1 5 
One may assign a single value to a series of variables by 
stringing the assignments together: 
varl _ var2 _ var3 _ exp I 

The asslgnisent will be made frow right to left* varl* 
var2* and var3 will all be given the value of the 
expression. 
Example: 

a _ b _ ; 

Both a and b will be given the value zero* This type of 
statement can be useful In Initializing a series of 
variables at the beginning of a procedure* 
BUHP Statement 

The BUHP statement will add one to a variable: 
BUHP var » 

This Is equivalent to: 
y&r _ var ♦ 1 ♦ 
BUf*!P DOyN will subtract one frora a variable: 

sum ooyw var ; 

This Is equivalent to: 
var __ var - 1 I 
You way BUMF more than one variable In a single statesient: 

8UHP varlt var2» var3»**. I 
or 

BUMP DOUI^ varl* var2* var3*... ; 
IF Statement 

This form causes execution of a stateaent 1f a tested 
expression Is TRUE* If the expression Is FALSE and the 
optional ELSE part Is present* the statement following the 
ELSE Is executed* Control then passes to the statement 
iiBBiediately following the IF statement* 

IF testexp THEN statement » 

IF testexp THEN statement 1 ELSE stateifient2 » 
The statements within the IF statement can be any statement* 
but are not followed by the usual semicolon* the whole IF 
statement Is treated like one statement and followed by the 
semicolon* 
E*g* 

IF y=z THEH y_y*l ELSE y_z ? 
In some cases* complex nested IPs may be simpler If rewritten 
as a CASE stateiiient* 
CASE Statement 

This form Is similar to the IF statement except that It causes 
one of a series of statements to be executed depending on the 
result of a series of tests* 

CASE testexp OF 

relop exp : statement * 
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relop exp : statement » 
re lop exp : stateiient ♦ 

• 
EMDCASE stateiient I 
where relop ~ any relational or Interval operator €>=♦ <• 
= t If^f etc#> see Section 5 (5e3c) and C5e3d)» 
The CASE statement provides a means of executing one statewent 
out of atany. The expression after the word "CASE** Is 
evaluated and the result left In a register* This Is used as 
the left-hand side of the binary relations at the beginning of 
the various cases* Each expression Is evaluated an4 compared 
according to the relational operator to the CASE expression* 
If the relationship Is TRUE* the statement Is executed. If 
the relationship Is FALSEt the next expression and relational 
operator will be tried* If none of the relations Is 
satlsfledf the statement following the word "ENDCASE* will be 
executed* Control then passes to the statement fol lowl ng the 
CASE statesient 

Mote that the relop and expressions are followed by a 
colont and the statements are ternilnated with the usual 
semicolon* The word Ef^OCASE 1s not followed by a colon* 
In ENDCASEt the statement may be left out — » this Is the 
equivalent of having a NULL statersent there; nothing will 
happen* 
Exaaip le: 

CASE c OF 

= a: %executed If c = a% 

X _ yl 
> b: ^executed If c > b% 

Cx» y ) _ <x+yt x-y) \ 
ENDCASE %executed otherw1se% 
y _ x; 
CASE char OF 

= O: Ilf char = the code for a digltx 

char _ •!; 
= UL: %1f char = the code for an upper-case letter % 

char _ 'O; 
ENDCASE;' atotherwlse noth1ng% 
Several relations may be listed at the start of a single case? 
they should be separated by coiBiias* The statement will be 
executed If any of the relations Is satisfied* 
CASE testexp OF 

relop exp: statement » 
relop exp • relop exp: statement » 
relop exp t relop expt relop exp: statement 5 
* 
• 
EI^OCASE statetnent t 
Example: • 
CASE e OF 

=at <d: %executed If c=a or c<d% 

X _ y? 
>b» =d : %executed If c>b or c=d% 

Cx»yl __ (x+y»x-y); 
ENDCASE iexecuted otherwisel 
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y _ x; 
As a point of stylet the conditions of the CASE statement 
should be put one level below the CASE statement In the source 
Ctext> file. The statements (1f they are wore than oneHneJ 
fBay be put one level below the condition. 
LOOP State{i\ent 

The statement following the word ••LOOP* Is repeatedly executed 
until control leaves by roeans of soiRe transfer Instruction 
within the loop* 
LOOP statefsentl 

where statei^ent = any executable LIO statement 
Exawple: 

LOOP IF a>=b THEN EXIT LOOP ELSE a _ a+1 ? 
CIt Is assumed that a and b have been Initialized before 
entering the loop.) 
The EXIT construction Is described below* It 1s extrewely 
Ifiiportant to carefully provide for exiting a loop* 
yHILE.*.00 

This stateiient causes a statement to be repeatedly executed as 
long as the expression IfRnedlately following the word SifHILE 
has a logical value of TRUE or control has not been passed out 
of the 00 loop by EXIT LOOP (described below)* 

yHILE exp DO statement t 
exp Is evaluated and If TRUE the statement following the word 
00 Is executed; exp Is then reevaluated and the statement 
continually executed until exp Is FALSE* Then control will 
pass to the next statement* 

For exaroplet If you want to fill out a string with spaces 
through the 20th character posltlont you could: 

WHILE str*L < 20 00 *str* _ *str*» SP; %what»s already 
theret then a space% 

Remember that the first word of e\/ery string variable 
has two globally defined fields: 

L — actual length of contents of string variable 
?f — maximum length of string variable 
The WHILE construct Is equivalent to: 
LOOP 

IF MOT exp THEN EXIT LOOP 
ELSE statement I 
Statement 
UNTIL* ••00 State»ent 

This statement Is similar to the WHILE*. •DO statement except 
that the statement following the 00 Is executed until exp Is 
TRUE* As long as exp has a logical value of FALSE the 
statement will be executed repeatedly* 
UNTIL exp DO statement ♦ 
Example: 

UNTIL a>b DO a _ a+l » 
The UNTIL construct Is equivalent to: 
LOOP 

IF exp THEN EXIT LOOP ELSE statement ; 
00** •UNTIL/ DO*.. WHILE Statement 

These statements are like the preceding statementst except 
that the logical test Is made after the statement h es been 
executed rather than before. 
00 stateffient UNTIL exp; 
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DO statement yHILE exp; 
Thus the specified statement Is always executed at least once 
Cttie first tiRte* before the test Is madel* For exaaiplet this 
DO. ..until: 

00 arrayCvarl _ UNTIL Cvar := var - 1) = I 
and this DO.. .WHILE: 

DO arrayEvar3 _ WHILE Cvar := var - I> > ♦ 
are both equivalent to: 
LOOP 

BEGIN 

array Cvar 3 _ 5 

IF Cvar := var - 1> =t THEN EXIT LOOP ; 

emd; 

FOR. ..00 Statement 

The FOR statement causes the repeated execution of the 
statement following "DO* until a specific tercilnal value Is 
reached. 

FOR var UP UMTIL relop exp DO statementl 

CUP will be assutsed 1f left out.J 
FOR var BOUH UNTIL relop exp DO statessent? 
where 

var = the variable whose value Is Incresiented or 
decremented each tliiie the FOR statement Is 
executed 
relop = any relational operator Cdescrlbed in 5e3cl 
exp = when combined with relopt determines whether 
or not another Iteration of the FOR statement 
will be performed. It Is recofuputed on each 
Iterat Ion. 
E.g. FOR 1 UP UI^TIL > 7 DO a _ a ♦ tC13 ? 
Optionally* the user may Initialize the variable anc Riay 
Increment It by other than the default of one. 

FOR var _ expl UP exp2 UWTIL relop exp3 DO statement; 
FOR var I expl DOWN exp2 Uf^TIL relop exp3 DO statefnentl 
where 

expl = an optional Initial value for \far» If expl Is 
not speclfiedf the current value of \far Is used. 
exp2 = an optional value by which var will be 
Incremented Clf UP specified! or decreajented C1f DOWN 
specified*. If exp2 is not specified! a value of one 
will be assumed. 
Mote that exp2 and exp5 are recotuputed on each Iteration. 
ExaiBpLe: 

FOR k _ n UP k/2 UHTIL > m*5 DO xCk3 _ k? 
is equivalent to 
k n? 
LOOP 

SEGIN 

IF k >fs*3 THEN EXIT LOOP I 
xCkl k; 
k _ k~+ k/2; 
END! 
BEGIN*. .Ef^D Statement 

The BEGIi^...Ef^O construction enables the user to group several 
statements Into one syntactic statefpent entity. A BEGIN...EMD 
construction of any length is valid where one statefient Is 
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required. 

BEGIN statement I statement t ••• END I 
ExampleZ 

IF a >= b*c THEM 
BEGIN 

END %no sepicolofi here because an LIQ 
statement here wouldn't have one? see 5d4% 
ELSE 

BESIN 
a_cl 
b~d+2; 
c_b*d*7; 

tUDl %this semicolon terminates the entire IF 
statement % 
Mote the use of MLS file structure to clarify the logic and 
separate the blocks. Blocks should always be put one level 
below the statement of which they are a part. 
EXIT Statement 

The EXIT statement transfers control (forward) out of CASE or 
Iterative statements* A CASE statement can be left with an 
EXIT CASE statement. All of the Iterative statements (LOOPt 
yniLE, UNTILt DOf FOR) can be exited by the EXIT LOOP 
statement. EXIT and EXIT LOOP have the saae meanino. 
EXIT LOOP nam or EXIT num 
EXIT CASE num 

where num Is an optional Integer. The optional number 
Cnuifi) specifies the number of lexical levels cf CASE or 
Iterative statements respectively that are to be exited 
fe.g. If loops are nested within loops). If a number Is 
not given then 1 1s assuined. 
Exaroplesi 
LOOP 

BEGIN 

*.*..• •• 

IF test THEM EXIT; 

%the EXIT will branch out of the LOOP% 



ENO; 
UNTIL something DO 
BEGIN 



yHILE test! DO 
BEGIM 



IF testa THEI^ EXIT; 

%the EXIT will branch out of the yHILEX 



end; 



ENOI 
UNTIL something DO 

BEGIU 



yHILE testl 00 
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THEN EXIT 2; 
EXIT 2 will branch out of the UNTIL% 



5- 


-Jan -8 2 


15:05 

BEGIN 

IF test2 
Ithe 

end; 




end; 

CASE exp OF 
=sojRet hing: 
BEGIN 






IF test 
%the 




• 1 


emd; 



THEN EXIT case; 

EXIT will branch out of the CASE% 



REPEAT Statement 

The REPEAT statement transfers control Cbackward> to the front 
of CASE or iterative statesients. The optional number has the 
sasse meaning as In the EXIT statement. REPEAT and REPEAT CASE 
have the same sieanlng. 

REPEAT LOOP nutn 

REPEAT CASE num (exp) or REPEAT nua Cexpl 
If an expression Is given In parentheses with the REPEAT CASEt 
then It Is evaluated and used In place of the expression given 
at the head of the specified CASE statesient# If the 
expression Is not glvent then the one at the head of the CASE 
statement Is reevaluated. 
Examples: 

CASE expl OF 
=someth1ng: 
BEGIN 



IF testl THEN REPEAT; 

%REPEAT with a reevaluated expl% 



IF testa THEM REPEATCexp2) 5 
%REPEAT with exp2X 



end; 



EflDCASE ; 
LOOP 

BEGIN 



IF test THEN REPEAT LOOP? 

%REPEAT LOOP will go to the top of the LOOPI 



EPio; 

DIVIDE Statement 

The divide statement permits both the quotient and reaialnder 
of an Integer division to be wasted* The syntax for the divide 
statement Is as follows: 

DIV expl / exp2 ♦ quotient f rcBialnder » 
Quotient and remainder are variable natftes In which the 
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respective values y1Ll be saved after the division* 

DIV a / bf a» r i 

a will be set to a/b to the greatest Integer with r 
getting the remainder 
Floating point calculations are described In Part Flvet 
Section 4« 
PROCEDURE CALL Statement 

Procedure calls direct progrars control to the procedure 
specified* A procedure call occurs when the nafie of the 
procedure Is followed by parentheses* If the procedure 
requires that arguiients be passed* they should be Included 1n 
the parentheses t separated by cofRntas* 
procname Cexpt expt •••> I 
where procname = the naroe of a procedure 

exp = any valid LIO expression (explained In Section 5)* 
The set of expressions separated by corentas Is the 
argument list for the procedure. 
The argument list consists of a number of expressions 
separated by coatatas* The nuieber of arguaents should equal the 
nufRber of formal parameters for the procedure* The argument 
expressions are evaluated In order from left to right* Each 
expression (parafseter) must evaluate to a one-word value. The 
values will be assigned to the forwal parameters of the called 
procedure* 

To pass an array* text pointer^ string^ or any multi-word 
paraiBeter* the prograssier may pass the address of the first 
word of the variable* then REF the receiving local In the 
called procedure* 

For examplet one may pass an stid directly* but to pass a 
text polntert you roust pass the address of the text pointer 
and REF the receiving parameter* Reiiiesiber that a dollar 
sign C$) preceding a variable represents the address of 
that variable* 
The procedure »ay return one or sore values* The first value 
Is returned as the value of the procedure call* Therefore* If 
only one value Is returned* one might say: 
a _ proc Cb) ♦ 

In this context* the procedure call Is ar\ expression* 
If more than one value Is returned by the called procedure* 
one Biust specify a list of variables In which to store thesi* 
The list of variables for multiple results Is separated irom 
the 11st of argument expressions by a colon* The nuaiber of 
locations for results need not equal the number of results 
actually returned* If there are »ore locations than results* 
then the extra locations get an undefined value* If there are 
more results than locations* the extra results are slfiiply 
lost* The first RETURf»i value Is still taken only as the value 
of the procedure call* 

var _ procnane <exp* exp* •** : var* var* •••> » 
Example: 

If procedure "proc* ends with the statement 

RETURN {a*b»c> 
then the statement 
q _ proc C: r*s> f 
results In (q*r*s> (a*b«c)* 
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A procedure call »ay just exist as a states ertt alone without 
returning a value. I^ot all procedures require paraaieterst but 
the parentheses are iBandatory In order to distinguish a 
procedure call froin other constructs. 

E.g. IdaO; 
If a block of Instructions are used repeatedly* or are 
duplicated In different sections of a progra«t It Is often 
wise to make theK a separate procedure and simply call the 
procedure when appropriate* 

It Is considered good style to "iBodularl ze* the functions 

of your program as much as possible* where each procedure 

represents a function which will foe performed no matter 

which procedure called 1t» This Implies very limited use 

of global variables and careful definition of the procedure 

interface. 

Procedures should not be made too long* nor have complex 

nested loops. Often breaking the code Into a nuiriber of 

shorter procedures will wake the program clearer an4 easier 

to debug. 
A procedure may recursively call Itself. Each call w1 1 1 have 
Its own unique set of local variables. This may be useful If 
a procedure 1s built to handle a general case as well as a 
specific case or number of cases. The general case may call 
that same procedure for the specific case after some 
manipulations. 

A great many procedures are part of the NLS system and are 
available to your programs. A list of them 1s available In 
the file <ftlLStXFROCSt> or <NLS*SYS60f>. SYSGD lists links to 
the source code* so that you can examine the procedure In 
detail to see just what It expects as arguments and what It 
returns. 
RETURI^ Statement 

This statement causes a procedure to return control to the 
procedure which called It. Optionally* It may pass the 
calling procedure an arbitrary number of results. The order 
of evaluation of results Is from left to right. 

RETURN ; 

RETURN Cexp* exp* ...I ? 
E.g. 

RETURN (TRUE* a+b> ; 

RETURN f getnmfCstId) ) ; 
GOTO Statement 

Any statement may be labeled; one puts the desired label Ca 
string of lower case letters and digits* In parentheses and 
followed by a colon at the beginning of a statement. 

C label): statement ♦ 
E.g. 

(there): a ^ b + c I 
GOTO provides for unconditional transfer of control to a new 
location. 

GOTO label I 
E.g. 

GOTO there ; 
GOTO statements make reading and debugging your program 
difficult and are not considered good style* they can usually 
be eliminated by use of procedure calls and the Iterative 
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stateroents* 
NULL Statement 

The NULL statement siay be used as a convenience to the 
programmer^ It does nothing* 
I^ULL ; 
Example: 

CASE exp OF 

=o» =i: null; 

ENDCASE y_i; 
JSYS Call and Asse«ibly Language Statesient 

The use of these capabilities should be limited to systesi 
ppograiBfners* Assembly language code makes user programs 
difficult to understand and to maintain as the executive 
underlying f^LS changes over time* LiO procedures are 
available to accomplish most of the tasks one reight want to do 
with a JSYS* System prograesRiers should refer to the TEMEX 
JSYS manual for a description of the available JSYS*s. 
Assefsbly language stateinents may be included in the LIO code 
by preceding the statement with an exclamation-point il>m The 
Instruction fRust be upper-case; the argusnents aiust be 
lower-case. E«g* 

IPUSH stjfn ; 
A TENEX JSYS fsay be invoked with a stateiRent similar to the 
procedure call statement; the naiee of the JSYS must be 
lower-caset preceded by an exclawation-point : 

Ijsysnaine (regit reg2f«»*) I 

E.g. IgjinfC) ; 
The arguffients in the parentheses are evaluated and loaded into 
the registers before the JSYS is Invoked. The first argument 
will be put in register onet the second in register two* etc. 
Up to eight arguments may be given. 

Like a procedure callt niultiple results aay be received. They 
will be taken in order from the registers. (See <13510»3c> 
for a description of user JSYS calls. 

SoRie JSYS return to the asseinbly-language line of cede (not 
the LIO statement) one beyond the norwal return location, 
yith such JSYS* you may use the SKIP construct to test if it 
has done so: 

IF SKIP ! jsys(arglt...> THEN ... ; 
In using SKIP* you may not receive wultiple results directly* 
but Jfiust read the registers into globals (see 5cl2) . 
Section 5: Expressions 
Introduction 

This section will describe the composition of the expressions* 
which are an integral part of many of the statements described 
1n Section 4. 
Pr luiit ives 

Primitives are the basic units which are used as the operands 
of LIO expressions. There are aiany types of elements that can 
be used as LIO primitives; each type returns a value which is 
used in the evaluation of an expression. 
Each of the following Is a valid primitive: 

a constant (see below) 

any valid variable natRe* refering to the contents Cof the 

first word* if not Indexed) of that variable 

the contents of a string variablet refered to as *var* 
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a dollar sign CS) followed by a variable name% referlng to 

the address of the variable 

a procedure call which returns at least one value 

the first {leftmost) value returned is the value of the 
procedure call? other values may be stored In other 
variables as described 1n Section 4» 

an assignment (see below> 

classes of characters! described In Section 1 of Part One 

KIN (exp* expf •••* the iRln1®yiB of the expressions 

HAX Cexpt expf •••) the fnaxIfRum of the expressions 

TRUE has the value 1 

FALSE has the value 

VALUE Castr1ng> given the address of a string cortalnino a 

decimal nuBiber* has the value of the nurober 

VALUE Castring* nunt) given the address of a string 
containing a number and the base of that nusiber* has the 
value of the number (allows other than base-ten numbers) 

READC (see below) 

CCPOS (see below) 

FIMD 

used to test text patterns and load text pointers for 
use in string construction (see Section 611 returns the 
value TRUE or FALSE depending on whether or not all the 
string tests within It succeed. 

POS 

POS textpolnterl relop textpo1nter2 

may be used to cofspare two text pointers. If the POS 

construction Is not usedt only the first words of the 

pointers (the stid's) will be compared. If a pointer Is 

before anothert It Is considered less than the other 

pointer. 

E.g. 

POS ptl = pt2 
POS first >= last 
Constants 

A constant may be either a nufpber or a literal constant. 

There are several ways In which numeric values may be 

represented. A sequence of digits alone (or followed by a 

0) Is Interpreted as base ten. If followed by a B then It 

Is Interpreted as base eight. A scale factor nay be given 

after the S for octal numbers or after a D for decimal 

numbers. The scale factor is equivalent to adding that 

many zeros to the original nuisber. 
Examples: 

64 = lOOB = 1B2 
1448 = 100 = 1D2 

Literals may be used as constants as they are represented 

Internally by numeric values. The following are valid 

literal constants: 

-any single character preceded by an apostrophe 

e.g. ♦a represents the code for 141B. 
-the following synonyms for coisitionly used characters: 
EMDCHR — endcharacter as returned by READC 
SP — space 

ALT -- Tenex's version of altmode or escape (=33B) 
CR — carriage return 
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LF — line feed 
EOL -- Tenex EOL character 
TAB — tab 

8G — backspace character 
By — backspace word 
Cm — center dot 
CA -- Command Accept 
CD — CoiRPand Delete 
Asslgnroents 

An assignment can be used as a value in an expression. 
The form a _ b has the effect of storing b into a and has 
the value of b as the value of the assignasent* 
Another forre of the asslgnipent statement is: 
a I' b 

This will store b into at but have the old value of a as 
the value of the asslgniuent when used as a pri«itive in 
an expression* 
For exaiaplet 

b _ (a := b) 1 

The value of b will be put in a* The assigninent will 
get the old value of at which is then put in b* This 
transposes the values of a ar^d b» CThe parentheses 
are not really necessary.) 
REAOC - ENDCHR 

The primitive REAOC Is a special construction for reading 
characters frofn WLS statements or strings* 

A character is rQa<i irom the current character position 
in the scan direction set by the last CCPOS statement or 
string analysis FIND statement or expression* CCPOS an6 
FIND are explained in detail in Section 6 of this 
document* 

Attempts to read off the end of a string in either 
direction result in a special "endcharacter" being 
returned and the character position not being moved* 
This endcharacter is included in the set of characters 
for which system mneuiiionics are provided and may be 
referenced by the identifier "ENDCHR"* 

For exaiBple* to sequentially process the characters 
of a string: 
CCPOS *str*« 

UNTIL <char _ READC) = EMOCHR DO proces sf char) I 
(Note: REAOC raay also be used as a statement if it is 
desired to read and sifuply discard a character). 
CCPOS 

yhen used as a primitive^ CCPOS has as its value the index 
of the character to the right of the current character 
position* If str = "glarp^t then after CCPOS *str*f the 
value of CCPOS is 1 and after CCPOS SEt*str*) the value of 
CCPOS is 6 lone greater than the length of the string)* 
CCPOS is more coRimonly used as a statement to set the 
current character position for use in text pattern 
matching. This is discussed in detail in Section 6* 
CCPOS may be useful as an index to sequentially process the 
first n characters of a string (assuiaed to have at least n 
characters)* 
Example: 
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CCPOS SF(*str*)l 

%CCPOS now has the Index value of onet the front 
of the str1ng% 
UNTIL CCPOS > n DO process€READCH 

%READC reads the next character and increments 
CCPOSI 
Operators 

PrlRi1t1ves may be combined with operators to form expressions* 

Four types of operators will be described here: a rlthmetlct 
relational* Intervalt and logical. 
Arithmetic Operators 

♦ fin front of a number) — positive value 

- Cin front of a number) — negative value 

♦ — addition 

- — subtraction 

♦ — multiplication 

/ ~ Integer division Creroalnder not saved) 
MOD -- a MOD b gives the remainder of a / b 
•V — (OR) a .V b => bit pattern which has l»s where either 
a or b contains It elsewhere 

•X — CXOR) a .X b => bit pattern which has l»s where 
either a holds 1 and b contains 0» or a contains and b 
contains It elsewhere 

•A -- <AWD) a .A b => bit pattern which has l*s where both 
a and b contain 1» elsewhere 
Relational Operators 

A relational operator Is used In an expression to compare 
one quantity with another* The expression Is evaluated for 
a logical value* If truet Its value Is 1* If falset Its 
value Is 0* 
Operator leaning Example 



= equal to 4*1 = S-i-a f TRUEt =1) 

# not equal to 6#8 (TRUEt =1) 
< less than 6<8 (TRUEt =1) 
<= less than or 

equal to 8<=6 (FALSE* =G) 
> greater than 3>8 (FALSEt =0) 
>= greater than or 

equal to 8>=6 (TRUE* =1) 
NOT <o the r-re I at Ion a I -opera tor > 

6 MOT > 8 (TRUE* =1) 
Interval Operators 

The Interval operators permit one to check whether the 
value of a primitive falls In or out of a particular 
Interval* 

IW (primitive* primitive) IN Cprlsiltlve* pr1fBlt1ve3 
The value Is tested to see whether or not It lies within a 
particular Interval* Each side of the Interval may be 
"open" or "closed"* Thus the values which deterilne the 
boundaries raay be Included In the Interval (by using a 
square bracket) or excluded (by using parentheses)* 
ExafRple: 

x IN EltlOO) 
1s the same as 

(X >=1) AND (x < 100) 
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Logical Operators 

Every nuiBerIc value also has a logical value. A numeric 
value not equal to zero has a logical value of TtUt5 a 
nuinerlc value equal to zero has a logical value of FALSE • 
OR 

a OR b = TRUE If a = TRUE or If b = TRUE 
= FALSE If a = FALSE artd 1f b = FALSE 

a mD b = TRUE 1f a = TRUE an6 If b = TRUE 
= FALSE If 3 = FALSE or If b = FALSE 

noi 

NOT a = TRUE If a = FALSE 
= FALSE If a = TRUE 
Expressions 

Introduction 

An expression Is any constantt variable* special expression 
foraif or combination of these joined by operators and 
parentheses as necessary to denote the order 1n which 
operations are to be perfornfied. 
Examples of assigning an expression to a variable: 

var __ O; 

var __ var * 2 l 

var _ POS ptrl >= ptr2 I 

var ~ (a > b) OR Ca IN Cct d3> ; 
Liberal use of parentheses Is highly recosfsrended • 
Special LIO expressions are: 

- the FIND expression which Is used for string 
Rianlpulat iont and 

- the conditional IF and CASE expressions which may be 
used to give alternative values to expressions depending 
on tests fiade In the expressions* 

Expressions are used where the syntax requires a value. 
While certain of these forsis are similar syntactically to 
LIO statementst when used as an expression they always have 
values Csee below). 
Order of Operator Execution-- Binding Precedence 

The order of perforielng individual operations within an 

equation is deteriained by the hierarchy of operator 

execution Cor binding precedence) and the use of 

parentheses. 

Operations of the sawe heirarchy are performed from left to 

right in an expression. Operations in parentheses are 

performed before operations not in parentheses. 

The order of execution of operators ffroBi first to last) Is 

as follows: 

unary -t unary ♦ 

.A 

.Vf .X 

*♦ /f HOD 

♦t - 

relational tests le.g*» >=f <=§ >§ <f =♦ it INt OUT) 

NOT relational tests fe.g.t NOT >) 

NOT 

Af^O 

OR 
Conditional Expressions 
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The two conditional constructs CIF andi CASE> can be used as 
expressions as well as stateraents* As expressionst they 
must return a value* 
IF Expressions 

IF testexp THEN expl ELSE exp2 

testexp Is tested for Its logical value* If testexp Is 

TRUE then expl will be evaluated* If It Is FALSEt then 

exp2 Is evaluated* 

Therefore t the result of this entire expression Is 

EITHER the result of expl or exp2* 

ExaiBple: 

y _ IF X INC If 3 3 THEN x ELSE 4; 

%1f X = If 2t or 3f then y_x I otherwise y_4% 
CASE Expression 

This form Is s1«1lar to the above except that It causes 
any one of a series of expressions to be evaluated and 
used as the result of the entire expression* 
CASE testexp OF 

relop exp t exp I 
re I op exp : exp * 
relop exp : exp ♦ 
* 
• 
EMDCASE exp 
where relop = any relational or interval operator 
C>=f <f =f IMf etc* See above C5e3c) and C5e4d) 
In the abovef the testexp Is evaluated and used with the 
operator relops anfi their respective exps to test for a 
value of TRUE or FALSE* If TRUE 1n any Instancet the 
coiBpanlon expression to the right of the color Is 
executed and taken to be the value of the whole 
expression* A value of FALSE for all tests causes the 
next relop In the CASE expression to be tested against 
the testexp* If all relops are FALSE» the ENDCASE 
expression Is taken to be the value of the whole 
expression* 

Note that ENDCASE cannot be nulll It must have a value* 
As with the CASE statesientf any number of cases may be 
specif ledf and each case luay Include more thar one reidp 
and expresslonf separated by coiRstas* 
Exaotplet 



y _ CASE X 


OF 


<3: 


x+i; 


=3f =4: 


x*2? 


=5: 


x; 


ENDCASE 


x*2; 


Value of X 


Value of y 


2 


5 


3 


5 


4 


6 


5 


5 


6 


12 



String Expressions 

LIO also provides several expression forras which are used 
for string stanlpulation and evaluation* These are 
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discussed In Section 6 of this document* yhen using string 
iRanlpulat ion statement fonss as expresslonst parentheses 
ffiay be necessary to prevent ambiguities* 
Section 6: string Test and Hanlpulatlon 
Introduction 

This section describes statements which allow complex string 
analysis and construction* The three basic elements of string 
manipulation discussed here are the Current Character Position 
iCCPOS) and text pointers which allow the user to dellislt 
substrings within a string Cor statefRent)f patterns that cause 
the systeia to search the string for specific occurrences of 
text and set up pointers to various textual elements* and 
actual string construction* 
Current Character Position (CCPOS) 

The Current Character Position Is similar to the TNLS CH 
€Control Marker) In that It specifies the location In the 
string at which subsequent operations are to begin. All LIO 
string tests start their search from the Current Character 
Position* In Content Analyzer programs* It Is Initialized to 
the BEGIMhflNG OF EACH MEy STATEMENT* For each new statenentt 
the scan direction Is Initialized to LEFT TO RIGHT* It 1s 
fitoved through the stateaient or through strings by Flt^D 
expressions* It siay be set to a particular position in a 
statement or string by the LIO stateiRent: 

CCPOS pos » 
pos Is a position In a statement or string that may be 
expressed as any of the following: 

A previously declared and set text pointer* 

If a text pointer Is given after CCPOSt then the 
character position Is set to that location* A text 
pointer points between two characters in a string. 
e*g. CCPOS ptl I 
String Front -- left of the first character 
SFCstspecJ 

yhen SF is specif iedt CCPOS will be set before the first 
character of the statement or string variable specified 
by stspec* 

stspec Is a string specification that aiay be expressed 
as 

• an stid Ce*g* the first computer word of a 
previously declared text pointer)* or 
- a previously declared string name enclosed in 
asterisks* 
ExaotplesX 

CCPOS SFfptl) I 

%ptl is a text pointer% 
CCPOS SFCstid) ; 

Xstid is an stid% 
CCPOS SF(*str*> ; 
%str is a string% 
String End — right of the last character 
SE est spec) 

yhen SE Is specified scanning will take place from right 
to left* and CCPOS will be set after the last character 
of the statement or string variable specified by stspec* 
A string <*str Ingname*) is given after CCPOS* The position 
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Is moved to the beginning of that string • 

Indexing the strlngnaifie iby specifying Cexp3> siroply 
specifies a particular position within the string* Thus 
♦str*E33 puts the Current Character Position between the 
second and third characters of the string "st r"» If the 
scan direction Is left to right* then the third 
character will be read next» If the direction Is right 
to leftf then the second will be read next» 
E.g. 

CCPOS *str*C33 ; 
If no Indexing Is given* then the position Is set to the 
left of the first character In the string. This Is 
equivalent to an Index of 1. 
E.g. 

CCPOS *str* f 

ffieans the same as 
CCPOS SFC*str*j; 
Setting the current character position with the CCPCS 
statement also sets the scan direction to forward 
C lef t-'to-rlght > t except If the SE construct Is used. 
FIND Statement 

The FIND statement specifies a string pattern to be tested 
against a statement or string variable* and text pointers to 
be manipulated and set* starting from the Current Character 
Position. If the test succeeds the character position Is 
moved past the last character read. If the test falls the 
character position Is left at the position prior to the FIND 
stateraent. The values of text pointers set in the statement 
prior to the falling element will rejsaln as set* others of 
course will not be changed. 

FIND pattern ; 
FINOs may be used as expressions as well as free-standing 
elements. If used as an expression* for example In IF 
statements* It has the value TRUE If all pattern elements 
within It are true and the value FALSE If any one of the 
elements Is false. 
E.g. 

IF fim pattern THEN ... ; 
It Is good practice to use FIND as an expression with the 
appropriate error conditions If the FIND falls. If the FIND 
falls* text pointers may not be set as expected. 
FIND Patterns 

A string pattern Bay be any valid combination of the following 
logical operators* testing arguments* and other non~test1ng 
parameters (note the Identity with Content Analyzer Patterns): 
Pattern Pfatching Arguments — 

(each of these can be TRUE or FALSEI 
string constant* e.g. "ABC" 

or any character* preceded by an apostrophy 

It should be noted that If the scan direction Is set 

right-to-left the string constant pattern should be 

reversed. In the above exafsple* one would have to 

search for "CBA". 

Any of the system defined innemonlcs* as described In 

the last section C5e2c)» such as "SP" or "CR"* are 

also valid. 
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character class 

look for a character of a specific class; If found? = 
TRUE* otherwise FALSE* 
Character classes: 

CH — any character 

L -• lowercase or uppercase tetter 

UL — uppercase letter 

LL — lowercase letter 

— digit 

LD -- lowercase or uppercase letter or digit 

I^LO -- not a letter or digit 

ULD -- uppercase letter or digit 

LLD — lowercase letter or digit 

PI — printing character 

HP — nonprinting character 

Example: 

char = LD 

Is TRUE If the variable char contains a value 
which Is a letter or a digit* 
Celements ) 

look for an occurrence of the pattern specified by 
the elefsents* If foundf = TRUE? otherwise FALSE. 
Elements may be any pattern? the parentheses serve to 
group the elements so as to be treated as a single 
element In any of the following elements, 
-element 

TRUE only If the string constant or character class 
element following the dash does not occur. 
NOT element 

TRUE only If the element or group of eleaents 
following the MOT does not occur. 
C elements 1 

TRUE If the pattern specified by the eleiisents can be 
found anywhere In the remainder of the string, 
elements may be any pattern? the squarebracket s also 
group the elements so as to be treated as a single 
element. It first searches from current position. 
If the search failed^ then the current position Is 
Incremented by one and the pattern Is tried again. 
Incrementing an6 searching continues until the end of 
the string. The value of the search is FALSE if the 
testing string entity Is not matched before the end 
of the string Is reached. 
NUH element 

find (exactly) the specified number of occurrences of 

the element. 

E.g. 

5CLD> means three letters or digits 
Hum $ Hum element 

Tests for a range of occurrences of the element 
specified. If the element Is found at least HUHl 
times and at most HUH2 times* the value of the test 
Is TRUE. 

Either number 1s optional. The default value for 

HUni is zero. The default value for NU^2 is 

10000. Thus a construction of the form "S3CCH>» 
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woyid search for any nusiber of characters 
ClRctudimg zero> up to and including three* 
Examplest 

2$4CUL) — from two to four upper-case letters 
$10(SPI — up to ten spaces 
!$(♦•> -- one or wore periods 
ID = user-ldent 
ID i user-ldent 

If the string being tested Is the text of an HLS 
statement then ident of the user who created or last 
edited the stateaient is tested by this construction; 
If CCPOS Is In a strlngt you will get the error 
"string treated as stateiuent* 
FT var 

rnUE If the variable holds a value of TRUE 
{non-zero)» 
sri^CE datlffi 

If the string being tested Is the text of an NtS 
statement* this test Is TRUE If the statement was 
created or modified after the date and tlfiie CdatlfR* 
see below> specified* 
BEFORE datlfB 

If the string being tested Is the text of an NLS 
statementf this test Is TRUE If the statement was 
created or modified before the date and time <dat1p* 
see below> specified* 

Acceptable dates and tloies follow the forais permitted 
by the TENEK system's IDTIH JSYS described in detail 
In the TEMEX JSYS manual* It accepts "stost any 
reasonable date and time syntax*" 
Examples of valid dates: 
17-APR-70 
APR-17-70 
APR 17 70 
17 APRIL 70 
17/5/1970 
5/17/70 

APRIL 17f 1970 
Examples of valid times Czero assumed If time left 
ou t > : 

1234 
1234:56 
i:56A« 
i:56-EST 

1200M0ON 

16:30 C4:30 PH> 
12:00:00AH Cmldnlght) 
ii:59:59AH-EST (late morning) 
12:oo:01AM tearly morning) 
Examples: 

BEFORE (HAR 19* 73 16:49> 
SINCE (25-jyL-73 2130 :00> 
These may not appear In Content Analysis patternst but are 
valid elements 1n FIMD statements In any program: 
•strlngname* 
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the contents of the string variable 
BETIIEEM pos pos C element! 

Search limited to between positions specified* pos 
Is a previously set text pointer? the two must be In 
the saifie statement or string. Scan character 
position Is set to first position before the pattern 
Is tested (This 1s not an unanchored scan unless 
square brackets are used within the parent heses*) • 
E •§• 

BEiyEEN ptl pt2 C20 r.3 $f4P) 
Logical Operators — 

These combine and delimit groups of patterns. Each 
compound group Is considered to be a single pattern with 
the value TRUE or FALSE. The character position will be 
reset to Its position before encountering the group before 
a new group Is tested. Any text pointers set within a test 
pattern before It falls will retain their new values. (See 
examples below.) 
/ 

AND 
OR 

These logical concatenators bind In the order In which 
they are listed. I.e. 
a / b ANO c 

means the same as 
(a / bJ AND c 
Other Elejfients-- 

These do not Involve tests! rather* they Involve sofse 
execution action. They are always TRUE for the purposes of 
pattern matching tests. 

These may ai^pear In simple Content Analysis Patterns: 
< 

set scan direction to the left 

In this caset care should be taken to specify 
patterns In reverse* that Is In the order which 
the computer will scan the text. 
> 

set scan direction to the right 
TRUE 

has no effect* It 1s generally used at the end of OR 
when a value of TP.UE Is desired even If all tests 
fall. 
ENDCHR 

Atteapts to read off the end of a string In either 
direction result In a special "endcharacte r» being 
returned and the character position Is not moved* 
This endcharacter Is Included 1n the set of 
characters for which system sineuffionlcs are provided 
and may be referenced by the Identifier "EMDCHR*. 
These may not appear In sli^ple Content Analysis Patterns* 
but may in FIMD statements: 
pos 

pos Is a previously set text pointer* or an SEtpos> 
or SFtpos) construction. Set current character 
position to this position. If the SE pointer Is 
used* set scan direction frosi right to left. If the 
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SF painter Is usedt set scan direction from left to 
r1ght» 

FIND x| %sets CCPOS to position of previously set 
text pointer x% 
** ID 

store current scan position Into the textpclnter 
specified by t^e Identifier 
tnuni ID 
back up the specified text pointer by the specified 
nuwber (NUH> of characters* Default value for NUM 1s 
onem Backup Is In the opposite direction of the 
current scan direction. 
FS var 
FR \iar 

FS yllt set the variable to TRUE CI). Ft will reset 
the variable to FALSE (0)* 
String Construction 

One may modify an MLS statement or a string with the 
statement: 

ST pos _ strlngllst » 

The whole statement or string In which pos resides will 
be replaced by the string list. 
ST pos pos _ strlngllst » 

The part of the statement or string from the first pos 
to the second pos will be replaced by the string list* 
"pos" may be a previously set text pointer or the 
SF(pos)/SECpos> construction. 
There are two additional ways of modifying the contents of a 
string variable: 

ST *str1ngnafBe*Cexp TO exp3 _ strlngllst ♦ 

means the same as 
*str1ngnai!ie*Cexp TO exp3 _ strlngllst t 

The string from the first position to the second 
position will be replaced by the string list* The 
square-bracketed range Is entirely optional* If It Is 
left offf the whole string will be replaced. 
Note that the "ST* Is optional when assigning a 
strlngllst to the contents of a string variable. The 
statesient then reseiebles any simple assignment 
statesient. I.e. 

*str1ngna!Be* _ strlngllst I 
The string list Cstr1ngl1st> may be any series of string 
designators* separated by corowas. The string designators may 
be any of the following: 
the word NULL 

represents a zero length CeiRpty) string 
string constant* e.g. "ABC* or •« 
part of any string or statesientf denoted either by 

two text pointers previously set In either a statement 
or a string 

pos pos 
a string name in asterisks* refering to the whole string 

*str1ngname* 
a string nafse In asterisks followed by an Index* 
refering to a character In the string 
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*stringnai8e*texp 3 

(The Index of the first character 1s one»> 
a string name In asterisks followed by two Indlcest 
referlng to a substring of the string 
*str1ngname*CeKp TO exp3 

A construction of the forsi *str*C1 TO j 3 refers to 
the substring starting with the 1th character 1n 
the string up and Including the jth character* 
Examples: 

*str*C7 TO 10 3 Is the four character substring 
starting with the 7th character of str» 
*str*C1 TO str*L3 Is the string str without the 
first 1*1 characters* CI Is a declared 
variable • > 
♦ substring 

substring capitalized 
- substring 

substring In lower case 
exp 

value of a general LIO expression taken as a character! 
I.e.* the character with the ASCII code value Csee chart 
at end of document J equivalent to the value of the 
expression 
STRING <explt exp2>; 

gives a string which represents the value of the 
expression expl as a signed decimal number. If the 
second expression Is presentt a nuiiber of that base is 
produced Instead of a decimal number* 
E» g« 

STRIMS C5*2) Is the same as the string "6* 

or 
STRING C14f8) Is the same as the string "16" 
Examples : 

ST pi p2 _ * string* I 

does the same as 
ST pi _ SF{pl) pit *str1ng*t p2 SECp2H 

assuming pi and p2 have been set somewhere In the same 
statement* The latter reads "replace the statefsent 
holding pi with the text froai the beginning of the 
statement to pl» the contents of strlngt then the text 
from p2 to the end of the statement*" 
*st*Clow TO highl _ "string"; 

does the same as 
*st* _ *st*ri TO low-13t "string"* *st*Ch1gh*l TC st*L3; 
assuming low and high are declared simple variables* 
Example: 

Let a "word" be defined as an arbitrary number of letters and 

digits* The text pointer "t" Is set before or after some 

character 1n the word* The two statements In this example 

delete the word which holds the text pointer "t"» ard If there 

Is a space on the right of the wordt It Is also deleted* 

Otherwise* If there Is space on the left of the word It 1s 

deleted* 

The text pointers ptrl and ptr2 are used to delimit the left 

and right respectively of the string to be deleted* 

IF €FIND t < $L0 '^ptri > $LD CSP "ptr2 / '*ptr2 ptrl < CSP 
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"ptrl / TRUEn > THEn 

ST ptrl ptr2 _ NULL; 
The reader should work through this exansple until it Is clear 
that it really behaves as advertised* 
Hore Than One Change per Statement 

The second word of a text pointer* the character count* stays 
the saaie until the text pointer is again set to sosie other 
position (as does the first word) t even though the statement 
has been edited* If* for exaiRple* you have the stateifient 
abcdef g 
/\ 
and if you have set a pointer between the *d" and the »e*» it 
will always point between the fourth and fifth characters in 
the statement; the second word of the text pointer holds the 
number 5» If you then delete the character "a** your pointer 
will be between the "e" and the "f*» 
bcdef g 
/\ 
For this reason* you probably want to do a series of edits 
beginning with the last one in the statement and working 
backwards* 
Text Pointer Comparisons 

This fiiay be used to compare two text pointers* 
POS ptl = pt2; 
M 
> 
< 

< = 
ptl and pt2 are text pointers* 
NOT Biay precede any of the relational operators* If the 
pointers refer to different statements then all relations 
between them are FALSE except "not equal" which is written 
# or ?^0T=* If the pointers refer to the sawe statement* 
then the truth of the relation Is decided on the basis of 
their location within the statement* 

A pointer closer to the front of the statement is "less 
than** a pointer closer to the end* 
Section 7: Invocation of User Filters 
Introduction 

The Content Analyzer filters described in this document may be 
imposed through the MLS PROGRAHS subsysteis* 

User-attachable subsysteiss may be written for iiore cosipiex 
tasks* This type of user program and MLS procedures which 
iiiay be accessed by thesi will be discussed in Part Four* 
yith such a prograw* however* the user will still stake use 
of the cofsiiiands in the NLS PROGRAMS subsystem* 
This section describes MLS cofflmands which are used to compile* 
institute and execute user programs and filters* 
Coffipilation-- 

is the process by which a set of instructions in a 
program is translated froni the LIO language written in 
an NLS source file into object code* which the cossputer 
can use to execute those instructions* 
Loading-- 

is the process which copies the compiled instructions 
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Into the yser-prograffis buffer. 
Inst Itytion-- 

1s the process by which a eowplled and loaded Content 
Analyzer prograBi Is designated as the current Content 
Analyzer filter. 
This section additionally presents exainples of the use of the 
LIO prograsimlng language. They do not inake use of any 
constructions not explained so far In this (nanual. 
Programs Subsystem 
Introduction 

The PROGRAHS subsystem! provides several facilities for the 
processing of user written programs and filters. It Is 
entered by using the MLS cofsiiiand: 

Goto Programs OK 
This subsystem enables the user to compile LIO user 
prografRs as well as Content Analyzer patternsi control how 
these are arranged Internally for different uses* define 
how programs are usedt and to see the status of user 
programs. 
PROGRAP^S subsystem coiBmands 

After entering the PROGRAHS subsystemt you way use one of 

the following cofBiaands: 

Show Status of programs buffer 

This command prints out information concerning active 
user programs and filters which have been loaded and/or 
Instituted: 

Show Status Cof programs buffer) OK 
yhen this command is executed the system will print: 

— the names of all the programs 1n the user programs 
buffer f Including those generated for simple Content 
Analysis patternst starting with the first program 
loaded. 

— the remaining free space In the buffer. The buffer 
contains the compiled code for all the current 
compiled programs. 

— the current Content Analyzer Program or "None* 
-- the current user Sequence Generator program or 
"None** 

— the user Sort Key program or "None" 
Compile 

LIO Program 

This command compiles the program specified. 

Compile LIO Cuser program at> ADDRESS OK 
ADDRESS Is the address of the first statement of the 
program. 

This command causes the program specified to be 
compiled and loaded Into the user program buffer In a 
single operation. The program Is not Instituted. 

The name of the program Is the visible following 

the word PROGRAM. ADDRESS points to the PROGRAM 

statement. 
The program may be Instituted by the appropriate 
commands. 
F1 le 

The user program buffer Is cleared whenever the user 
resets or logs out of the system. If you have a long 
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program which will be used perlodlcallyt you may wish 
to save the compiled code In a TENEX file. It can 
then be retrieved with the toad Program co^fsand. The 
cofflBiand to cosiplle the code Into a TENEX file Is: 

Compile File Cat) ADDRESS CuslngJ LIO OK Cto file! 
FILENAWE OK 
The FILENAME isust be the same as the program navie* 
The program will then be compiled ar\6 stored In the 
TENEX file of the given name (with the extension RELt 
unless otherwise specified) • The user ssay then load 
It at any time* 

Before doing this* the prograaimer must replace the 
word PROGRAM at the head of the program with the word 
FILE. 
Content Analyzer Pattern 

This coffiinand allows the user to specify a Content 
Analyzer pattern as a Content Analyzer filter. 

Compile Content (analyzer filter) ADDRESS OK 
The pattern must begin with the first visible after 
the AODRESSt or at that point you may type It In. It 
will read the pattern up to a semlcolont sc be sure 
to Insert a semicolon where you want It to stop. 
yhen this command Is executedt the pattern specified 
Is compiled Into the buffer* AWD It Is automatically 
Instituted as the Content Analyzer filter. 
Procedure 

This command compiles a single procedure. 

Compile Procedure (at) ADDRESS OK 
ADOR ESS Is the address of the PROCEDURE statement. 
This command causes the procedure specified to be 
compiled and loaded into the user program buffer 1n a 
single operation. 

If a procedure of the same name has already been 
loaded (In the user programs buffer or In the NLS 
system)* the old procedure will be replaced. I.e. 
any calls to that procedure name will Invoke the 
newly compiled procedure. 
Error Message during Compilation 

*SYWTAX ERROR* messages Include the type of error* 
the location of the line of assembly code that caused 
trouble* and a few characters of the NLS source code. 
The last of these characters Is the one which caused 
the error. In some cases this may be misleading* 
when a previous error (e.g. a missing quote or 
percent sign) caused trouble later In the 
compilation. 

**ext & local** — a symbol was used as both an 

external or global and a local variable In the 

file. If a variable Is not declared In the 

program* the compiler assumes It Is a system 

EXTERNAL. If It Is later used as a LOCAL* an 

error will result. 

"field too large" -- a field may not be defined as 

more than 36 bits. 

"sides not equal" -- In a multiple asslgntient 

statement* the sides must have the same number of 
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valuest e«g» (dtbvO _ (x«XfZ>; 

"not REF or POIMTER* — an ampersand C SI was used 
or> a variable not REFed or declared as 8 POIMTER 
(not described in this document l# 
**8 args max* — you may not pass wore than eight 
arguments in a JSYS call* 
"SYSTEH ERROR* messages also include the type of 
errort the location of the line of assembly code that 
caused troublet and a few characters of the WtS 
source code. 

•*EOF REAO« — the compiler hit the end cf the NLS 
file before it read a FINISH statement* (This atay 
happen If you don»t have viewspecs set to all 
lines ♦ all levels*) 

"HASH TABLE FULL** — you have used too many 
symbols in the file* Each file is liaiited to 
approximately 2000 sysibols* 

"BACKUP TOO FAR* — a symbol or a literal string 
(text within quotes) has too many characters in 
it* They are limited to 148 characters* 
»SYH80L TOO LONG* — as above» a syfflibol has too 
many characters in it* 

"INPUT TOO LONG" — as abovet a literal string has 
too iiany characters in it* 

*S*S* FULL* — as above* a syebol has t eo Bany 
characters in it* 

"I/O ERROR" — a nuiBber has too many digits in it* 
"LIT TABLE FULL" — the file has too isary literal 
strings and numbers* 
"PUSHDOyw OVERFLOy* means that one of the stacks that 
the coapiler uses overflowed* Look for an LIO 
statement containing too many parentheses or 
particularly complex constructions* You mey have to 
break some statements into multiple statements* 
"Boolean as operand" -- you used an expression as a 
parameter or in a RETURN statement* This is NOT an 
error? but only a warning of unusual {though in many 
cases good) programming practice* 
If you include the LIO statement 

NOMESS ; 
at the beginning of the file* at the saffe level as 
global declarations (i*e* not within a procedure) t 
this warning will not be printed* Errors will be 
printed as usual* 
yhen the compilation Is finished* It will list the 
number of errors and wait for a Command Accept to 
continue* You should then search for the error in 
the NLS source code filet correct itt and recompile 
before attempting to use the program* 

Errors involving undefined variables will be reported 
when you attempt to load the program* Of course any 
code using these variables will cause execution 
errors • 

If you include the LIO statement 

LIST ; 
anywhere in the code* all the undefined symbols at 
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that point In the compilation will be printed. 
The Compile Procedure command will generate 
undefined variable errors legitimately 1f the 
procedure refers to global variables* 
If the addition of your prograRi to the user programs 
buffer requires more than the »»ax1muffi space allotted 
for user programs (either In number of pages or 
number of symbols Jt you will get a "forsrat error* 
upon loading* Clf you have any other programs 
loadedf use the "Delete All* coBiaand prior to 
loading.) 

NODT (described In Part Five* Section 21 will help 
you trace run-time errors to errors In the NLS source 
code* 
Load PrograiB 

A pre-conrplled program existing as a REL file may be 
loaded Into the program buffer with the cofnisafid: 

Load Program FILENAHE OK 
If the FILENAME Is specified without specifying an 
extension nasie* this coaifRand will search the connected 
dlrectoryt then the CPR06RAHS> directoryt for the 
following extensions: 

REL — It will simply load the REL file 
CA — It will load the programs and Institute It as 
the current content analyzer program 
SK — It will load the program and Institute It as 
the current sort key extractor program 
S6 — It will load the program and Institute It as 
the current sequence generator prograiR 
SUBSYS -- It will load the program and then look for 
a file of the same name with extension CHL * If both 
are successfully loaded* they will be treated as a 
single program 

CML — It will load the program and then try to 
attach It as a subsystem 

PROC-REP — It will load the program and then try to 
replace an existing procedure of the same name as the 
TEf^EX code file by the first procedure In loaded 
program 

Sort key extractor and sequence generator programs 
are siore complex and are generally limited to 
experienced LIO programmers* 
FILENAME Is the name of the TEMEX code filet not the 
name of the program. 

If any variables are undeflnedt they will be reported 
upon loading* The program should not be used until 
those variables are declared somewhere. 
Delete 
All 

This command clears all programs from the user 
program buffer* All programs are delnstltuted and 
the buffer Is marked as empty* 

Delete All (programs in buffer) OK 
The user programs buffer shares memory with data 
pages for files which the user has opent therefore 
Increasing the size of the user programs buffer 
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decreases the aiRount of space available for file data 
with a possible slowdown in response for that user» 
The buffer size is increased autofBaticaliy as needed* 

This comwand also resets the buffer size to the 
original 8 pages Csaving system storage space! • 
Last 

This cofliRiand deletes the roost recently loaded program 
in the buffer* The prograsi is deinstituted if 
instituted and its space in the buffer fiarked as 
free* 

Delete Last (program in bufferl OK 
Run Program 

This coffiBiand transfers control to the specified program* 

This type of program is used very little* having been 
substantially replaced by user-attachable subsystems* as 
described in Part Four* 

Run Prograai PROGNAME OK 
Run PrografB NUMBER OK 
PROGNAHE is the name of a program which had been 
previously compiled* That is* PROGMAHt must be in the 
buffer when this command is executed* 

Instead of PROGNAHEi the user may specify the program to 
be run by its number* This first program loaded into 
the buffer is number one* 
Institute Program 

This command enables the user to designate a program in 
the buffer as the current Content Analyzer* Sequence 
Generator* or Sort Key extractor program* 

Institute Program PROGNAME OK fasi type OK 
where type is one of the following: 
Content (analyzer) 
Sort (key extractor! 
Sequence (generator) 

If no type is specified* Content analyzer will be 
assumed* 
Instead of PRGGNAffE the user may specify the program 
to be instituted by number* The first program loaded 
into the buffer is number one* 
If a program has already been instituted in that 
capacity* it will be deinstituted (but not removed from 
the buffer). 
Oeinstitute Program 

This command deactivates the indicated program* but does 
not remove it from the buffer* It may be reirstituted 
at any time* 

Oeinstitute type OK 

where type is one of the following: 
Content (analyzer) 
Sort (key extractor) 
Sequence (generator) 
Assemble File 

Files written in Tree-Heta can be assembled directly 
from the MLS source file with the Assemble File command* 
This aspect of NLS programming will not be described in 
this document* 
Examples of User Programs 
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The following are examples of user programs which selectively 
edit statements In an NLS file on the basis of text matched 
against the pattern* For examples of LIO prograuml rg 
problemst you way find out how the standard NLS cosiirsands work 
by tracing them throught beginning with <NLSt SYKTAX* 2>» A 
table of contents to all the global MLS routines Is available 
to the user in <ftlLSf SYSGDt 1>. 
Example 1 -- Content Analyzer prograsi 

PROGRAM outname % resjoves the text and dellBilters C) of NLS 
stateisent names In parentheses froai the beginning of each 
stat eisent% 

DECLARE TEXT POINTER sf? 
(outnaroe) procedure; 

If FIND •€ f>l '^sf THEM %found and set pointer after 
naiJie% 
BE6IM 
%replace stsint by everything after pointer^ 

ST sf „ sf SECsf); 
%d1splay statement% 

RETURflCTRUE)! 
END 
^otherwise don't display state»ent% 

ELSE RETURNCFALSE)! 
EMO. 
FINISH 
Example 2 -- Content Analyzer program 

PROGRAM changed %Th1s program checks to see If a 
statement was written after a certain date. If It wast the 
string "ECHAI^GEDJ* will be put at the front of the 
statement •% 

(changed) PROCEDURE * 

LOCAL TEXT POINTER pt ? 

%remef!ibert CCPQS Is Initialized to the beginning of 

each new state?Bent% 

IF FIND '*pt SINCE (25-dAN-72 12:00) THEN 

%the substring of zero length Is replaced with 
«tCHANGED3"X 

ST pt pt _ •CCHANGED3"? 
RETURNCFALSE) ; 
END. 
FINISH 
PMT FOUR: Interactive LIO ProgramiRlng 
Section i: Introduction 

For many prograiftBiIng appllcstlonst 1t Is sufficient to accept 
statements one at a t1«e from the sequence generator and assume 
as an Initial character position the beginning of the statement 
Ca Content Analyzer program as described above). For lore 
complex appllcatlonsf you may have to write prograiss which skip 
around fllest between fltest and Interact with the user. These 
are not called by the sequence generator but "Attached" and then 
used like standard NLS subsystemst holding one or more commands. 
All the capabilities described above are available to such 
programs. 
There are two parts to every user-attachable subsystem: 

1) the LIO execution routines which do the file manlpulatlonst 
and 
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2) the coiBiiiand syntaxf specified In a language called Gowmand 
Heta Language ( CHL> t describing the user Interface cf each 
coflsfjiand in the user attachable subsystem. 
These two parts are two separate prograisst conipHed separately 
Into two REL files* The two programs are loaded In unison and 
together comprise the subsystem* 

Like LlOf source programs for the CML cosRpiler are free for® WLS 
files* CoHiffients may be used wherever a blank is permitted and 
the structure of the source file is ignored by the coropiler* CHL 
source programs are compiled into REL files with the Goiuplle File 
coiiRiand in the PROGRAHS subsystem!. CHL Is the compiler naine for 
the CHL compiler. 

The REL file name of the CHL code should have the extension 
"cwl". The REL file name of the corresponding LIO execution 
procedures should have the saroe first na^e as the CKL code 
file* and should have the extension "subsys*" If these 
conventions are followedf the Load Program coBmand in the 
PROGRAMS subsysteBi will autoiiat ically load both parts of the 
user subsystem and attach it» making it available for use* 
The user's subsystem may then be invoked by using the Goto or 
Execute commands* 
The CML program describes the command words* noise words* 
selection requests* etc* that make up an NLS command* The Cf^L 
code interacts with the user when he enters the sufosysteia and as 
he specifies commands* In the process of interacting with the 
user* the CHL code may call one or a number of LIO execution 
procedures which "do the work*** 

CHL automatically provides prompting* quest ionmark* and 
<CTRL-S> facilities* The CML syntax specification applies to 
both TNLS and DHLS (unless restricted by the programmer to one 
or the other)* and will conform to all user options with 
respect to prompting and to recognition and completion modes* 
The next section will describe CHL* and how to design the user 
interface. Section 3 explains the requirements of the LIG 
procedures which CHL calls* The remainder to Part Four discusses 
additional LIO capabilities useful in the context of attachable 
subsystems* 
Section 2: Command Heta Language (CHLI 
Introduction 

This section describes the Command Heta Language fCHL>* CHL 
allows the specification of the user interface to commands. 
The CHL program (the grammar) may call LIO procedures of a 
certain type Cdescrlbed in the next section)* The programs 
written in CHL are similar in structure to LIO programs* 
Typically* a CHL and an LIO program are used in uni son as a 
user attachable subsystem* A more technical presentation of 
CHL may be found In <20438*>. 
Program Structure 

The basic CHL program structure Is much like that of LIO 
programs* The program begins with a "FILE* statement las does 
an HO program) of the form: 
FILE name 

where name is the name of the program code (in lowercase 
letters and numbers* beginning with a letter) » It must be a 
unique symbol* different from the FILE name of the LIO code 
file* 
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The program ends with the statement Cllke L10>: 
FINISH 

yithin the program* one may have a series fin any order) of 

dec larat Ions f rulest and subsystems* 

As In LlOt all variables ysed In the program must be 
declared somewhere in the system* Other values and 
attributes must also be declared in CHL* 

Rules are defined sequences of the CHL elements described 
below* Rule names can be placed anywhere In a GHL command 
specification* yhen a rule is called within a command* it 
Is almost as if the CHL elements represented by that rule 
were Inserted at that point In the command* This allows 
the definition of general Interactions that may be of use 
In a number of commands or points in a command* 
Each program usually represents one or more subsystems* A 
subsystem may Include one or more commands* Each command 
is a rule itself* It may optionally include rules to be 
performed upon entering or leaving the subsystem* iOne 
enters a subsystem with the Goto or Execute commands* and 
leaves with the Quit command*) A subsystem may also 
include general rules defined throughout the subsystem* 

Each of these parts of the CKL program will be described 

Independently* The CML elements which make up rules will also 

be described. 
Subsystems 

A CKL program holds declarations* general rules which apply 

throughout the program* and subsystems (usually only one)* 

The Subsystem begins with a statement of the form: 
SUBSYSTEM name KEYWORD "NAME* 

where name Is the Internal name of the subsystem (primarily 
for debugging purposes) and NAME Is the name which the user 
must specify (in a Goto or Execute command) to access 
commands In the subsystem* 

These two names may be the same but they must be unique* 
different from the FILE names of the CHL and LIO files* 

A subsystem ends with the statement: 
END* 

yithin the subsystem* you may have any number of rules* 
A rule as described below will be known throughout the 
subsystem* but not outside the subsystem* 

A rule preceded by the word •COKKA^O* will be available as 
a command In the subsystem* It should begin with a command 
word element* E*g*: 

COHMAND zshow = '•SH0y«!L2! 

ent _ t»EXA«PLE"/"SAHPLE"> 

cokfIrm 

proc Cent) ; 
A rule preceded by the word •INITIALIZATION" will be 
executed whenever the subsystem is entered (either with a 
Goto or an Execute command from another subsystem)* E*g*: 
INITIALIZATION example = 

procl (ent) 

proc2 (ent) » 
A rule preceded by the word "TERMINATION" will be executed 
whenever the subsystem Is left (with a Goto or Quit command 
from this subsystem)* 
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A rule preceded by the word ••RENTRY" will be executed 
yhenever the subsystem Is reentered Celther with a Quit 
cofiiiRand from another subsystefn* having left this one with a 
Goto* or upon cofnpleting an Execute of a coaimand in another 
subsystem from this subsystefn>» 
Preceding a rule with the above modifiers does not prevent 
calling that rule from within another rule* 
Rules 

A CHt rule is a defined series of elementsf each of which 
represents one piece of the interaction with the user or 
systeffi action. The eleisents will be described below. The 
name of a rule (defined to be the given series of CHL 
elements) may be used in other rules* yben the name of a rule 
appears in another rule* the CHL code which it represents will 
be executed at that point* 
A rule takes the form: 

name = elementl elewenta elements ••• element ♦ 

where "name* is any unique name (lowercase letters and 

nufibersf beginning with a letter)* 

Alternative elements (where the user has a choicel are 

indicated by a slash (/I in the expression* Parentheses 

should be used to group elewentst particularly when 

alternative logic and nesting of alternatives is involved* 

E.g* 

name = (elementl / ele{ient2 elementSJ eleaient4 I 
Note that* by use of parentheses* an alternative ^ay 
include more than one element* 
Elesjents grouped in square brackets are options* and the 
user laust type the option character <CTRL~u> to access 
theia* E*9* 

nasie = eleaientl Celeiiient2 elements 3 eleBient4 » 
E*g* 

zinsert = "I^ISERT" ent_(»yORD»/*CHARACTER"> <'*at«> 
dest_OS EL (en 1 1 x 1 ns ( des t > ♦ 
A nuwber of elements may be included in a single rule* (If 
you exceed the siaxiaiuBi* you will get a "stack overflow" error 
at run-time*! Elements are NOT separated by any delimiter 
character (except by spaces or the source file structure)* 
The entire rule is terminated by a seaiicolon* 

The return value of elewents may be assigned to CHL variables 
(single-word as in LIOI* using a left-arrow (_) in the forw: 
variable _ element 

The variable must have been declared* as described below* 
A variable must be initialized by such an assignment before 
its content is passed to any routine* It must be initialized 
in the rule which passes it to a routine (not just in other 
rules called from the given rule* even though other rules may 
subsequently set it to another value)* (If you fail to do so* 
you will get the run-time error "reference to undefined 
interpreter variable*") 

Names on the left side of an assignment are assumed to be 
variables* other names in CHL rules are assumed to be CHL 
rules* 
Declarations 

Declarations are used to associate names with their CHL 
function* A number of types of names may be used in CHL 
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programs* 
Variables 

yhenever a procedure Is called froB CHtt CML creates a 
ten-word record. The address of the record Is passed to 
the procedure? which siay put information In any of the ten 
words» The procedure usually returns the address of its 
record. 

A CML variable is a cell which holds the address of a CML 
record* By this mechanisfflt up to ten words of infor»ation 
may be handled with a single parameter by passing the 
address of the first word of the record* A variable may be 
declared with the statement: 

DECLARE VARIABLE name ; 
or 

DECLARE naifie ? 

where *na«e* is any unique naaie (lowercase letters and 

nusibersf beginning with a Letter!* 
You may declare any number of variables in a single 
statesentf i*e*: 

DECLARE VARIABLE naiuel* nafBe2f.** I 
or 

DECLARE namelf naffie2f*** I 
Many CML variables have been declared for use anywhere in 
the system* and may be used freely in user attachable 
subsystems C without being declared by the user programmer I* 
Some commonly used variable names arel 

ent nawfil level param 

dent dest filtre par am2 

sent source vs paramS 

port fromwhom literal param4 
External Variables 

As in LlOf external variables are variables which are made 
available to any procedure anywhere in the HLS system* 
(SimpLe variables are only known in the file in which they 
are declared*) One or more may be declared with a 
statement of the form: 

DECLARE EXTERNAL naroelt name2f •*. ; 
Parsefunct ions 

An LIO function which processes input and supplies a prompt 
string is called a ••parsefunct ion*" The name of the 
procedure must be declared as a parsefunction for CML to 
request a prompt string whenever the procedure is called* 

DECLARE PARSEFUNCTIOW namel » name2f*** t 
Pore detailed information about the nature of 
parsefunctions will be offered below* 
Command Words 

A command word is a word specified as part of a command 
(e»g* "Insert* or ••yord" in the Insert yord command) * it is 
specified in accordance with each user's recognition scheme 
(often recognized after the first character)* A 
declaration may assign a value to a command wordt to be 
passed to an LIO procedure which needs to know which 
command word was chosen by the user* 

DECLARE COMHAMD yORD ••yORDl ••=1 00* »yORD2«»=iOl t ... I 

The value must be a positive decimal integer* less than 

511. (This limit may have to be changed to 255 in 



HARYf 5-Jan-82 15:05 < USERGUIOESt PROSRAHHERS-GUIO E.AU6Uf > 63 

future versions of MLS.) 

Here than one cbfRmand word may have the sa^e value 
(unless of course the LIO procedure roust distinguish the 
user^s choice between the twol • 
A comntand word that has not been declared way be Included 
In the syntax; 1t will have no value though* Only those 
cofBRiand words which are assigned a value and then passed to 
an LIO procedure wust be dec la red • flany cowMand words have 
been declared for use In the HLS system* It Is considered 
good practice to use cowiBBand words already known to users 
when posslblet and to use the same values for these words 
as declared In NLS» Section 5 offers a set of 
declarations f Including all the systeii defined command 
words! It can be copied as the foundation for a CML 
program* 

You may not use command words Identical to the naises of 
the LIO or CML files* to the name of the subsystem* nor 
to any variable names* 
CHL Elements 

The CML elements described here are the building blccfcs of 
rules* which describe interactions with the user* 
Cowaand yord Recognition 

The appearance of a corosiand word eletient In a rule aieans 
that the user isust specify that (or an alternative cocieiand 
word> at that point in the comaiand specification* 

In the CML description* each cowntand word is represented 
by Its full text* The algorithi!! used to »atch a user»s 
typed Input against any list of alternative coRraiand 
words Is known as "recognition** Each Individual's 
command word recognition mode will determine what 
characters the user must type to specify the coBiBand 
word* This is handled automatically by the ccBiBiand 
Interpreter* 

As the user specifies a comiBand* the comwand words (and 
noise words described below > are echoed in a line at the 
top of the DNLS screen* or printed in TNLS* This is 
called the "coasaand feedback line*** 
Comraand word elements isust be uppercase words enclosed in 
double-quotes ("">; e*g* 

"INSERT" 
CoiBwand words optionally iRay be followed by one or iBore 
qualifiers which flsodify the recognition process* separated 
by spaces and enclosed In exclaination points* The 
qualifiers are: 

NOTT ~ not available In TNLS 
NO TO — not available in DNLS 

L2 -- second level (some recognition nodes differentiate 
first from second level comrBand words* e*g* second level 
are preceded by a space) 

number — explicit value for comaiand wordt supercedes 
any value assigned by a DECLARE COWHAND klORD 
For example: 
•SET»!L2! 
•PRINT»lNOTO! 
•EXAHPLEyORD»!L2 104! 
The address of records holding declared command word values 
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may be assigned to CML variables so that the user^s choice 
can be passed to subsequent routines* e«g« 
ent _ "CHARACTER" 

or 
ent _ ("CHARACTER" / "yORO"> 

then 
xprocedure Cent) 

RefRewber that* like all other CKL ssslgnwentst the 
variable receives the address of a record which holds 
the Information* yhen the content of this variable (the 
address of the record) Is passed to a procedure* the 
procedure must REF Its receiving variable to access the 
contents of the record* the value* 

This value will be assigned as above even If the coffiiRand 
word 1s followed by ather CHL elements* e*g» 

ent _ ("CHARACTER" paraai.FAtSE / "yORD" <"at"> 
paraiii_LSELC#"yORD») ) 

ent will get the value of the cownand word CHARACTER 
or the value of the command word yORO* The 
appropriate actions will happen after the user 
chooses the coiRstand word* 
You may wish to pass this value without forcing the user to 
type the cosiaiand word* This address Jsay be assigned by 
preceding the cofSBiand word by a pound-sign Ci)* 
ent _ «"CHARACTER» 

will assign the address of the declared cofnatand word 
value without forcing the user to type the comsand word 
Selection Recognition 

Selections are Input from users pointing to places In files 
or typing In strings of text* The three types of selection 
routines available In CHt* with their respective comffiand 
prompts* are: 

DSEL — destination selection 

3/A 
SSEL -- source selection 

B/A/CT3 
LSEL -- literal selection 

B/T/CA3 
where B = bug (not available In TNLS) » A = Oyra«1c 
Address Element (any series of NLS addressing elements >♦ 
and T = typein from keyboard* 
Each of these predefined selection routines prompts the 
user and receives the Input* 

The selection routines must be passed the address of a 
record holding the value of a noun coiuiBand word 
(character* word* statement* plex* etc*)* The command 
word enclosed In double-quotes and preceded by a 
pound-sign (#) Is equivalent to the address of a record 
holding the declared value of that cofflBiand word* e*g*: 

D$EL(#»CHARACTER") 
Or you i8ay have assigned the address of the value of a 
previously selected command word to a CHL variable* then 
pass the content of the variable* e*g*: 
ent _ "CHARACTER" 
OSElTent ) 
CHL will prompt the user for the appropriate Input* If 
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fRore than one selection is necessary Ce»g» to specify 
both ends of a group or string of text If they will 
profRpt for both autofnatlcal ly. They yitl del1?Blt the 
appropriate entity automatically Ce»g« both ends of a 
word will be found frons a single selection). 
The routine will return the address of a C^L recor€l 
holding two text pointers In the first four words? 
delimiting the beginning and end of the entity selected* 

for string entitles within statements 

words 1-2: txt ptr before first character of 
string 

words 3-4: txt ptr after last character of string 
for types »STATEf4ENT» and "BRANCH* 

words 1-2: txt ptr before first character of 
statement 

words 3-4: txt ptr after last character of 
statement 
for types •GROUP" and "PLEX" 

words 1-2: txt ptr before first character of first 
statement 

words 3-4: txt ptr before first character of last 
statement 
for type "yiNOOy" 

word 1: address of display area 
word 2: x and y screen coordinates 
One usually assigns the returned address of this record 
to a CKL varlablet e«g»: 

dest _ OSELC#«STATEHENT»> 
Other Recognizers 

Other prespeclfled Input routines are available* each 
prompting for and receiving a type of Input from the user: 
VIEySPECS -- takes no arguiBent and returns the address 
of a CHL record holding: 

word 1: updated viewspec word 1 
word 2: updated viewspec word 2 

words 3-7: used for collecting characters froia user 
LEVADJ — takes no argument and returns the address of a 
CHL record holding: 

word 1: level adjust count 

(up - ♦!* sa«e = Ot down = -1* up two levels = ^2% 
etc.) 

words 2-7: used for collecting characters froffi user 
CONFIRM -- waits for user to type confirmation character 
Ca Command Accept* Insert* or Repeat character)* It 
takes no argument and returns the address of a CNt 
record holding the conf Inflation code In word !• 
These values are rarely used* since subsequent 
functions are handled automatically by the cofsiuand 
parser. For reference* they are: 

1 = Conisiand Accept 

2 = Insert 

3 = Repeat 

DUHMY — does nothing but always TRUE; may be used to 
allow elements to be sklped* e.g.: 

C •'OPTION" soRiprocedureO / DUMMY ) COHFIRf* 
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allows the user to specify "Option** before the 
CONFIRHf or skip it and just type a COMFIRH. 
CHL Constants 

TRUE — holds the address of a CHL record whose first word 
has the value TRUE (i.e. 1> 

FALSE -• holds the address of a CML record whose first word 
has the value FALSE Ci.e. 0> 
LIO Procedure Calls 

LIO procedures may be called at any point in the rule by 
including the name of soroe routine followed by its 
paraineter list enclosed in parentheses* (The next section 
describes the special requirements of LIO procedures called 
frosi CHL.) E.g. 

procedurenawe (paraalt paraw2f...> 
Paraoieters may include CHL variables (whose content is 
passed) f the CHL elements TRUE t FALSE or NULLf or the # 
construct (see »Selection Recognition**) representing the 
address of a coatsand word value. 
Helpful Procedures in building CHL logic t 

isdnlsO — returns TRUE if DNLSt else FALSE 
istnlsO — returns TRUE if TNLS» else FALSE 
trueO — returns TRUE 
falseO -- returns FALSE 

abort (> — abort command as if user typed a CciBBiand 
Delete 
Parsefunct ions 

Procedures which are declared as PARSEFUNCTIONs examine the 
information being typed by the user during cotumand 
specification (characters going into the input buffer). 
CHL places additional requirements on LIO procedures 
declared as parsefunct ions* as described in the next 
section. They may be called from CHL like any other LIO 
procedure. The following parsefunctions are available as 
part of the running systewl they of course must be declared 
as parsefunctions in any program which uses them as such: 
answO — if the next character in the input buffer is a 
CONFIRH* option character» or the letter "y't it reads 
the character (out of the input buffer) and returns 
TRUE! else it reads the next character and returns FALSE 

answerO — reads next character? like answ« but returns 

the address of a CHL record whose first word holds 

either the value TRUE (1) or the value FALSE(O) 

look3nsw() — if next character is a CONFIRHt option 

character* or the letter '•y*»» returns TRUE and leaves 

next character in buffer? else returns FALSE and reads 

character 

mylookanswO — if next character is a COf^FIRHt option 

charactert or the letter •»y"* returns TRUE? else returns 

false; leaves next character in buffer 

readconf i rfn( ) -- if next character a CONFIRH character* 

reads and returns TRUE* else leaves character in buffer 

and returns FALSE 

lookconf i rii>( ) — if next character is a CO«*IFIRHt returns 

TRUE? else returns FALSE? leaves next character in 

buffer 
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readbygi) -- If next character a Com»and Accept 

charactert reads and returns TRUE? else leaves character 

In buffer and returns FALSE 

tookbugO -- If next character Is a Co»iRand Acceptt 

returns Ti^UEt else returns FALSE! leaves next character 

In buffer 

notcaC) -- If next character WOT a Coroinand Accept 

charactert reads and returns TRUE* else leaves Co^wand 

Accept character in buffer and returns FALSE 

readoptlonO -- If next character an option character* 

reads and returns TRUE* else leaves character In buffer 

and returns FALSE 

readrepeatO — if next character a repeat charactert 

reads andi returns TRUE I else leaves character In buffer 

ar\^ returns FALSE 

lookrptO -- if next character is a REPEATt returns 

TRUE* else returns FALSE* leaves next character in 

buffer 

spC) — If next character a space* reads and returns 

TRUE* else leaves character in buffer and returns FALSE 

lookback!) — if next character is a back-arrcw C_)t 

returns TRUE* else returns FALSE* leaves next character 

in buffer 

looknumC) — if next character is a digitt returns TRUE* 

else returns FALSE* leaves next character in buffer 

Parsefunctions may appear as alternatives to recognizers. 

Howevert they must precede any non-falling recognizers in 

the list of alternatives. E.g.: 

f lookconfirffiCX / •APPEND" / "FILE* > CONFIRM 
-- this example either will accept a CONFIRM or will 
accept a specification of the command word APPEND or 
FILE followed by a CONFIRM. 
Feedback 

Noise words between cofRmand words are very helpful to the 

user learning a new coBiBand. Any string of text raay foe 

added to the coiBwand feedback line by enclosing the text in 

parentheses and within angle-brackets in a rule. E.g. 
<*Text of noise words*> 

The last noise word string on the coisiBand feedback line Cin 

ONLS) siay be replaced with a new string by placing three 

dots before the first double-quote» e.g.: 
<..."new noise words*'> 

The last noise word string can be erased Cin ONLS) with the 

procedure call: 
c learnauteO 

The entire cosifiiand feedback line can be cleared Cin DNLSJ 

with the C«L element: 
CLEAR 

A few characters of the noise word will follow the cofuroand 

word in the system's response to a quest ionmark if: 

II the noise word IfiifBediately follows the comisand wordt 

and 

2> the command word is not being assigned to a variable 

lit may however be part of a list of alternatives being 

assigned). 

E.g. the noise words in the CHL below will show in the 
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systeiss response to a quest ionfaark : 

ent _ C«FILE" <"naaBe»«> / "STATEHENT" <»at»> ) 
Loops 

A looping facility perailts repetition of a different rule 
until an exit condition Is met* The rule Is evaluated and 
then the expression following the UNTIL keyword Is 
evaluated* If the expression returns TRUEt then the loop 
Is exited and the next element of the rule Is evaluated* 
If the expression returns FALSEt then the naaed rule Is 
Invoked once again* 

PERFORM rulenante UNTIL f exp I 

where rulenaine Is the name of the rule to be repeatedly 
executed and exp Is an expression of CML elements which 
evaluates to TRUE or FALSE. 
E • 9« 

PERFORM rulename UMTIL C <»Fln1shed?»> answil I 
Nested loops Cloops within rules called by a PERFORM 
element) are not currently allowed* Backspacing through 
executed loops requires special treatsient not described 
here* 
Sainple CML Program 

The following sample program should help Illustrate the use of 
the CML language for describing NLS coiiiiBands* For ffore 
exhaustive exa»ples» look at the CML specification for the 
standard MLS co^sandst In <NLSf SYNTAX f>* An exafsple of a 
problem treatment can often be found by thinking of an NLS 
command which Is similar* 

FILE sampleprogram % <CML»> to <sample*re l«> % 
DECLARE what* whomt where I 
DECLARE COHMANO yORO 
«GLUE" = It 
•PASTE" = 2f 
"CRAYONS" = 3t 
•PENS* = 4t 
"PENCILS" = 5 ; 
SUBSYSTtM sample KEyyORD "SAMPLE" 
objects = 

"GLUE" 
/ "PASTE" 
/ writlngthlngs » 
writ Ingthlngs = 
"CRAYONS* 
/ "PENS" 

/ "PENCILS" !L2! t 
COMMAND zuse = "USE" 
what _ writlngthlngs 
CLEAR 
<"to draw a pretty'*> whom ^ 

C "PICTURE" <"of Aunt Mary"> 
/ "SKETCH" <"of your dog»> 
> 
CONFIRM 

% call execution routine process the USE ccmmand % 
xuseC whatf whom! ♦ 
COMMAND ztake = "TAKE" 
what _ objects 
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<*oyt of your*> 

where C*EARS"!1! / *N0SE«I2! / »H0UTH*!3!J 
<*»PLEAiE«!»> 
CONFIRM 

xtake fwhatf where) I 
END. 
FINISH 
Given this sample CHL« the user slight specify the cowBiand: 
"Use Pens 

tto draw pretty) Sketch Cof your dog) <0K>» 
•Take Crayons (out of your) Mouth CPLEASE!!) <0K>" 
The execution routines called frop CHL typically have nawes 
beginning with the letter »x*« 
Section 5: LIO Execution Procedures 

The CHL prografu Interacts with the user and gathers Inforfflatlon? 
It subsequently calls one or more LIO procedures. The procedure 
CHL calls must weet certain requ1re«»entst described In this 
section. Because of these requlreatents ♦ typically the execution 
routine Is written as an Interface to a number of other LIO 
procedures perforsilng the actual functions. This way the 
function routines can be written Independent of which cowaiand or 
procedure calls theiit. This section will describe the 
requirements of procedures called froro GML. The next section 
offers additional LIO capabilities In this environment. 
CML can be In one of four states as it parses a comiiand based on 
the syntax described In your CHL program Cknown as the 
"parsefflode") : 

1) parsing: recognition state where Input text Is compared 
with grarufRatical constructs in CfIL progran 

2) backup: the user has typed a backspacev or a procedure 
call has returned FALSE? CHL backs up through previously 
specified elements of the CWL code* calling each in backup 
aodet to before the last CHL alternative (not necessarily 
equivalent to user input elenentf maybe through the entire 
compandf aborting the command) 

3) cleanup: the user has typed a Command Delete* or the 
command has been completed Cincluding any execution procedure 
calls)t CML backs up through all previously specified elements 
of the CML code; each procedure is again ca lied* this time in 
■cleanup** mode 

4) parsehelp: (used only with parsef unctions) before calling 
a parsef unction in •parsing" mode* the procedure is called in 
"parsehelp" mode to solicit a user prompt string. 

5) parseqmark: (used only with parsefunctions) when the user 
types a questionmark* the procedure is called in "parseqmark** 
mode to solicit a quest ionmark string. 

yhen CML calls a procedure* It automatically passes two extra 
implicit parameters before the parameters the programmmer 
specifies: 

The first parameter Is the address of a CML record reserved 
for use by that procedure. The record Is initially empty (or 
filled with garbage). The execution procedure may fill the 
ten words of the record by receiving the address in a REFed 
parameter variable and then indexing into the array. 

CML considers the procedure to have returned TRUE if it 
returns the address of the CML record? otherwise the return 
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Is considered FALSE, yhen a procedure returns FAtSEt CML 
will back upf calling that and previous procedures In 
"backup* iRodet until another branch In the cotRmand syntax 
logic Is found or until the entire cowiiand has been 
aborted. 
The second parameter Is a value (not an address of a record) 
representing the parse node* yhenever C«t encounters a 
procedure call In the syntax (In any model It calls the 
proceduref passing It the value of the parseBiode* 

Typically* the execution routine should only perform Its 
prlaary function In the parsewode "•parsing*. In "backup* 
and "cleanup*t It way reset any globals or state 
Information It may have affected while In the parsepode 
"parsing** The nawes of the aiodes fsee above) are globals 
to which you way compare the value received In the second 
parameter. An execution routine typically consists of a 
large CASE statementt e.g. 
CASE parse«ode OF 
= parsing: 
BEGIiy 



END I 
backup* = cleanup: 
BEGIN 



ENDf 
ENOCASE I 
Calls on procedures declared as parsef unctions pass a third 
Implicit parawetert the address of a string In which to put 
the prompt. They are called in the parsewode *parsehelp«» for 
the string before being called In the parseBOde "parsing"* or 
In parseaiode "parseqmark" when the user types a questionsiark . 
CWL passes the parameters specified in the call after the two 
or three system supplied parafneters. Reffiember that these 
parameters will always be the address of a record holding the 
Inf orwat Ion* so the receiving variable must be REFed. The 
format of the record itself Is determined by the routine that 
filled it. 

For example* If the CHL procedure call looked as follows: 
xprocedure Cparaml* paramZi 

then the LIO execution procedure would receive parameters as 

follows: 

(xprocedure) PROCEDURE (result* parsemode* parameterl* 
parameter2) » 

All parameters except the parsemode should be REFed In the 
execution procedure. 
Section 4: Additional LIO Capabilities 

Introduction 

The attachable subsystems have access to the full capabilities 
of the NLS environment. This section will describe some 
capabilities not discussed In the context of Content Analyzer 
programs. Further capabilities will be discussed in Part 
Five. 

Hoving Around yithin f^tS Files 
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Generallyt at least one slaiple variable or a text pointer will 
have to be declared to hold the statement identifier (stid) of 
the current statement* CThe first word of a text pointer 1s 
an st1d») Assufse the siRiple variable with the nasie *st1d* has 
been declared for the purpose of the following discussion. 
In the MLS file systernt two basic pointers are kept with each 
statement: to the substateiRent and to the successor* 

If there Is no substatementt the substatement-po Inter will 
point to the statement Itself* 

The procedure getsub returns the stid of the 
substatement* To do something to the substate»ent If 
there Is one: 

IF (stid := getsub(stld) ) « stid THEN sotae thing** ; 
stid Is given the value of the substateisen t-polnter ♦ 
then the old value of stid Is coRtpared to the new* 
If they are the safset then there Is no substructure* 
If they are dlfferentt you have the stid of the 
substateiRent and can operate on It* 
If there Is no successor Cat the tall of a plex> * the 
successor-pointer will point to the statement UP from the 
statement Cl*e* the statement to which the current 
statement Is a sub)* 

The procedure getsu.c returns the stid of the successor 
<or up>* 

To move to the successor: 
stid _ getsucCstIdH 
Given these two basic procedures* a number of other procedures 
have been written and are part of the NLS system* All of the 
following procedures take an stid as their only parasietert and 
do nothing but return a value* usually a stid* If the end of 
the file Is encounteredt these procedures return the global 
value »endf1l»* 

getupCstId) -- returns the stid of the up 
getprd(stld) — returns stid of the predecessor 
getnxt(stld) «- returns stid of next statement or endfll 
getbckCstId) — returns the stid of the back or endfll 
gethed(stld) -- returns stid of the head of the plex 
getallCstId) — returns stid of the tall of the plex 
getendCstId) — returns the stid of the end of the tall of 
the plex 

getftlCstId) -- returns TRUE If stid Is tall of plext else 
FALSE 

getlev(stld) — returns level of statenent 
Once you have the stid of a statement* you may operate on It 
as In Content Analyzer programs* E*g* 

FIND SFfst1d> $NP '^ptr.** 
Another coaiwon operation Is to access the statenient Cflle) In 
which the CH Cor bug> was at the time of the last Cofemand 
Accept Cor other comsiand terminator)* This Is stored In the 
systeffif and can be accessed with the following procedure call: 
stid _ IccspCI ; 

Then* If you wish to set the stpsid to the origin of that 
filet you could say: 

st1d*stps1d _ origin ; %orl9ln Is a global with the 
stpsid of the origin stateiBent In 1t% 
The following procedures may also assist you In isov Ing around 
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files: 

caddexp(aptrltaptr2f cfatstartpt r) -- given the addresses of 
two text pointers surroyndlng an NLS address expression* 
the address of a display area? and the address of a text 
pointer representing the starting position: caddexp will 
evaluate the address expression with respect to the 
starting positlont and update the start pointer to the new 
location. 

This procedure will follow file returns* links* etc»t 
opening files as necessary. ReroeiRber to close any open 
files when you are done with them (see 6d4 below>* 
The procedure IdaC) returns the address of the display 
area which held the bug at the time of the last Coiimand 
Accept; It may be used as the third parameter of 
caddexp* E*9. 

caddexpCSptrl* $ptr2f IdaOt Ssptr) % 
natRlngrp(st1dl tst id2tastr 1ngtlevels> -- given tw c stids 
representing a group* the address of a string holding the 
natae* and a number representing levels of depth below the 
stids*: returns stid of the statement with the given 
statement nawe in the group specified by the st1cs» Only 
searches through given number of levels below stid level* 
Clf the stids are the sasie* will search the branch.) 
lookupCptr*str1ng*type) — given the address of a text 
pointer* the address of a string* and a type* will do a 
variety of searches (in the process destroys string and 
changes pointer), type inay be one of the following: 

nasjetyp -• non-sequential search for statement of name 
given in string; returns stid and sets pointer to stid 
or else returns endfll In both places 

nxtnawe -- like name* also a non-sequential search* but 
starts froiR place In file ring to which ptr points 
seqname --' starting with the statement following the one 
refered to by the ptr* does a sequential search of the 
file for the given nanie» returns stid or endfll in 
pointer 

contnt — does a sequential search of the file* 
beginning with the character following the pointer* for 
a state»ent with the content of the string; returns stid 
or endfll In pointer 

contls — same as contnt* but looks only in statesient 
holding pointer 

wordtyp -- same as contnt* but looks for word given in 
string 

sId — pass an SID Instead of the address of the string* 
searches for stateiRent with that SID and returns In 
pointer and as procedure value the stid or encfll 
Calling NLS Commands 

A prograsi may execute any of the standard NLS cofURiands by 
calling the sawe procedure that the systeii execution routines 
call for each coBJinand. These procedures are called the ^core" 
procedures. They are listed In <NLS*XPROCS ♦> and In 
<NLS«SYSGD*>» Their names begin with the letter "c"* 
generally followed by three initials of each comaiand word* 
e.g. Insert Statement could be executed by calling the 
procedure "cinssta". 



HARYf 5-Jan-82 1.5:05 < USERGyiOESt PROGRAM«ERS-GUIO E.AUG;i ♦ > 73 

Usually the required arguments can be discovered by knowing 
the cofliBiand and by Looking at XPROCS and/or SYS&0» For 
exasjple* the forjnal paraieters to the procedure "clnssta" are 
<stid»rlevcnt«tplttp2) • As one might guess from the coBfiinand 
syntax? the procedure wants a target stidt the value of level 
adjustment Cup = +1* saine = Ot down = -1« etc)» and the 
address of two text pointers surrounding the string of text to 
be Inserted. 

Huch can be learned by looking at the code of the core 
procedure. You can see what procedures It In turn calls to 
discover how the command Is actually performed. But most 
ifflportantlyt you can find out what the procedure returns* The 
RETURN statement for "dnssta* look HkeX 

RETURI^(st1d> I 
frofR which It can be inferred that the procedure returns the 
stid of the newly created statement. 

yhen you are not sure what the arguments aieant a good way to 
find out Is to see where the cosuRand parser picks up the 
Information. You can follow through the parsing of a corsmand 
by beginning with <MLS»SYt^TAXt>» the actual NLS CHL code. 
Tracing a coroiriand from <NLStSYNTAXt> Is also valuable In 
finding out how the systew performs an operation which you 
would like your program to do. For exaroplet If you wish to 
parse a link and open the given filet you might learn how to 
do it by following the Jump to Link cowstand through. 
Opening Files 

yhen you ask the user for an address or bugt you don»t have to 
open the file? you have a handle on it with the stid the user 
gives you. There isay be tlasresf however? when you wish your 
program to open a file not specified by the user. There Is a 
procedure which does this: 

open ijfnt astring); 
You should pass zero as the jfnt and the address of a string 
containing the nawe of the file to astring. This procedure 
will return the file number. If the file Is not already open? 
It will open It. It will also fill out the string with the 
complete file na»e If you do not specify the directory or 
version nustber. 

If the file does not existt open calls the procecure '*err**% 
which generates a signal of the value "errslg." Signals 
are discussed in Part Five. 
The usual sequence of steps to open a file is as follows: 
%"st1d* has been declared as a siriple variable or text 
po1nter% 

stid _ orgstid; lorgstid is a global with all zeros except 
in the stpsid field* where It has the stpsld of the origin 
statenent Cthe same for every f1le>% 
*str* _ "<d1rnaiiie>f llename.nls"? %str is of course a 
declared string var1able% 
stid.stfile _ open C6t$str); 
Note that the procedure •open* requires a TENEX file nape. 
The procedure "Inbfls" converts links to TEMEX file names: 
Inbfls tlinkstr? linkparseblockt filenaRestr) 
Pass the address of the string holding the link as the 
first parameter* zero for the second parameter fused If 
link already parsedl? and the address of a string to 



«ARYf 5-Jan-82 15:05 < USERGUIOES* PR06R AMHERS-GUID E.AUGUt > 74 

receive the fllenaiBe as the third parameter* 
The procedure returns the host nuisber in case the link 
Includes a site nafiie* This value might foe cowpa red to the 
following globals: 

Ihostn — the number of the local host 
utilhost — the number of Off1ce-l 

archost -- the nu»ber of the ARC machine ( BBN-TENEX-B> 
For exawple* you wight use the procedure as follows: 
CASE Inbf Isf&l1nkstrt0f$f llename) OF 
= Ihostn: HULL* 
ENDCASE errCnotyet> ; 
At the end of your programt you should close any files that 
you have opened • Use the procedure: 
close {f1lnuiR>t 
E»g. 

close (st Id.stf lie) ; 
Displaying Messages 

The following procedures may be of use In displaying messages* 

In all casesf the appropriate actions will occur In TNLS as 
well as DlilLSt although these descriptions are oriented to 
ONLS. 

dlsmesCtypet astrlngj — teletype window 
where type Is one of the following: 

*- clear teletype window Cno address need be 
passed) 

1 -'- add text 1n string whose address Is passed as a 
new line In the teletype window 

2 -- add text In string whose address Is passed as a 
new line In the teletype window for about 3 seconds t 
then clear window 

n -- any number >=:1000 represents the number of 
milliseconds the message Is to be displayed before 
the teletype window Is cleared* 

In TNLSf type = !♦ 2t and >=1000 all simply print the 

string starting on a new line* 
fbctlCtypef astring) -- literal display window 

where type Is one of the following: 

typenullllt — begin empty literal display (replacing 

file window)? no string address passed 

fbaddllt -- add string whose address Is passed to 

current literal display 

addcallt -- add "Type <CA> to continue*" tc current 

literal dlsplayt then wait for <CA> or <CD>t then 

restore file window 

typellt — start literal display with string? then 

wait for user Input? then restore file window 

fbendHt -- add string to current literal dlsplayt 

then wait for user Input? then restore file window 

typecatit — start literal display with string? add 

"Type <CA> to continue*"? then wait for <C A> or <CD>? 

then restore file window 

The literal display replaces the file window on the 

screen? or Is simply printed 1n TMLS* For example? It 

Is used by the Show File Status conmand* 
dn(astrlng) -- name display 

add string whose address Is passed to command feedback 
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lincf enclosed In quotes 
Setting Up for Display Refreshing 

The coiBiiand parser calls the procedure "cpdflnlsh" after 
completing and cleaning up every cosfRiand. If certain 
parameters are set properlyt "ciadf Inlsh* will automatically 
update the user's screen Cprlmarlly of concern In ONLSI» You 
may also move a different statement to the top of the window 
fi.e. jump) before updating the screen* 
To refresh the screen after editing a file: 

The procedure "dpset* sets up paraaeters for refreshing the 
screen after a costiBand. If "dpset" Is properly usedt the 
screen will automatically be refreshed after the command* 
One should look for the atost efficient way to make the 
proper changes • 

The procedure "dpset* reust be called BEFORE any changes 
are wade in the file. This Is so that the display 
reforisatter will have something with which to compare 
when looking to see what has been changed* 
The procedure call should look as follows: 

dpset f typet stldlt st1d2f stopstid I ; 
There are a number of globals which may be passed for 
•type*: 

dsprfmt — rewrite the content of one or two 
statements 

stldl -- the stid of the statement that has been 
changed 

st1d2 -- the stid of another statement that has 
been changedt or "endfll* 
stopstid — Ignoredt pass It ••endfll* 
dspstrc -- If file restructuring occured beginning at 
at one or two placest doesn't rewrite content of 
statements; will add new statements In a structure 
stldl -- the stid of the statement where a 
structural change begins 

st1d2 — the stid of where another structural 
change beglnst or "endfll" 

stopstid — the stid of the statement after which 
It can stop changing the screen Cwhether change 
began with stldl or st1d2>; the procedure "dpstp" 
may be of service here? If you cannot figure out 
where It should stopt pass It "endfll* (go till 
enti of window I 
dsprfst — rewrites content of one or two statements* 
then looks for structural changes thereafter 

stidl -- the stid of the statement where a set of 
changes begins 

stida -- the stid of where another set of changes 
begins* or "endfll* 

stopstid — the stid of the statement after which 
It can stop changing the screen fwhether change 
began with stldl or st1d2); the procedure ^dps.tp" 
may be of service herel If you cannot f Igure out 
where 1t should stopt pass It "endfli* Cgo till 
end of window) 
dspjpf — jump command In one window only* no editing 
stldl -- the stid of the statement to be at the 
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top of the screenJ see below for other parameters 
which stust be set 
st1d2 — "endfll" 
stopstid -• "endfil" 
dspyes -- cowpletely refresh all windows holding one 
or either of two files specified 

stldl •• the stid of a statement In the file where 
changes will be taade 

st1d2 -- the stid of a statement In the file where 
another set of changes will be madet or "endfll* 
stopstid — "endfll" 
dspno — do no display refreshing 
stldl -- "endfll" 
st1d2 -- "endfll* 
stopstid — "endfll* 
dspallf — refresh the entire screen 
stldl — "endfll" 
st1d2 -- "endfll" 
stopstid -- "endfll* 
The procedure "dpstp"? when passed an stidt returns the 
stid of the next statement In the file at the saise or a 
higher level. This can be used as the stopstid In "dpset" 
If structural changes are occuring such that you don»t know 
a priori what the last statement changed will be* 
To change the position of a window Cjumpi: 

The global "cspupdate" should be set to the address of the 
display area descriptor for the window you want changed* 
In TNLSt It Is always the address contained In the 
global "tda*** 

If you wish to change the view In the window which held 
the bug at the time of the last CONFIR«» you nay use the 
statement: 

cspupdate _ Ida (II 
This also works for TNLS* 
Once cspupdate Is sett any of the globals described 
below will replace the appropriate field In the display 
area descriptor upon cospletlon of the co«wand« 
The global "curmkr* Is a text pointer pointing tc the 
stateisent at the top of a window In ONLSt or the CM In 
TMLS. 

The first word of "currokr* should be set to the stid of 
the stateisent you want at the top of the window Cin TNtS 
the statement which you want to hold the CH)» 
The second word of »curmkr"» 1«e» curmkrCllt should hold 
the character position for the CM. (In DHLS it 1s 
usually !•) 
The global *cspvs" Is a two word array which should hold 
two viewspec words for the new v1ew» 

The global stdvsp Is a two work array holding the MLS 
standard viewspecs C1.e« the ones In effect when you 
first enter I^LS)« 

The current viewspec words may be gotten from the 
display area descriptor* If you have REFed a variable 
called •da"* for example* you may assign the address of 
the display area which held the cursor at the time of 
the last cofTUBand Accept with the statefaent: 
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Ida _ IdaO « 
descr1ptor% 

You may then refer to field 

descriptor* 

davspec — holds the fir 
davspc2 -- holds the sec 

You isay change Individual f 

The following fields apply 
vslev — lowest level to 
vsrlev — If set to TRUE 
statement will be added 
vslevd — If set to TRUE 
current level will be su 
added to vslev 
vstrnc — nuBiber of line 
displayed 

vscapf -- If TRUE* conte 
takes precedence over vs 
vscakf — If TRUE* conte 
statement passes Cvlewsp 
vsusqf — If TRUE* user 
Cvlewspec 0) 

vsbrof -- If TRUE* branc 
precedence over vsplxf 
vsplxf — 1f TRUE* plex 



TRUE* 
TRUE* 



vsblkf — 1f 
vslndf — If 
default! 
vsrind — 
statement 
vsnasif — 
by default) 
vsstnf — If TRUE* 
(viewspec m> 
vsstnr — If TRUE* 
right Cvlewspec G) 



vssldf -- 
Cvlewspec 
vsldtf — 
K) 

vsfrzf -- 
vspagf — 



If 
I) 
If 



%return address of display area 

s within the display area 



st view spec word 

ond viewspec word 

lelds within viewspec words* 

to viewspec words: 

be displayed 
* the level of the 
to vslev 

&nd vsrlev Is TRU 
btr acted froiR rath 

s of each stateiien 

nt analyzer on Cvl 

cakf 

nt analyzer on unt 

ec 1) 

sequence generator 

h only on Cvlewspe 

only on Cvlewspec 

lines on Cvlewspe 
ting on Cvlewspec 

ting relative to f 

ewspec Q> 

ment names on Cvie 

went numbers or SI 

Rent nuisbers/SIDs 

replace statenent 

ment signatures on 



blank 
Inden 



If TRUE* Inden 
In display Cvl 
If TRUE* state 



state 

state 

SIDs 

state 



TRUE* 
TRUE* 



current 




E* the 




er than 




t to be 




ewspec 1) 


• 


11 one 




on 




c gl ; tak 


es 


I) 




c y> 




At on by 




Irst 




wspec CI 


on 


Cs on 




put on 




ruBbers 




Cvlewspec 



If TRUE* froze 
If TRUE* pagin 
on by default) 
vsdaft — If TRUE* don«t 
DNLS Cvlewspec u? on by 
If you wish* you may set the v 
address of a user content anal 
variable "cspusqcod* to the ad 
generator procedure? they will 
window Is updated* 

The following fields In the 
be useful: 

dacacode ~- holds addres 
Content Analyzer procedu 
dausqcod -- holds addres 
user Sequence Generator 



n stateiRents on Cv 
atlon on In TNLS C 



lews pec ol 
viewspec El 



defer display recreation In 
default) 

arlable "cspcacod* to the 
yzer procedure* and/or the 
dress of a user sequence 

be Instituted before the 

display area descriptor way 

s of currently Instituted 

re 

s of currently Instituted 

procedure 
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If you have a REFed variable called "da^t will not edit the 
filet and do not wish to change the vlewspecst ycu might 
use the following sequence of co««ands: 
%dddress of last display areaX 

&da _ cspupdate _, IdaCH 
Xstid of stmnt to be put at top of w1ndow% 
cu rmkr „ stid ? 
curffikrCl 3 _ 1 * 
%two current viewspec yordsX 
cspvs _ da.davspecf 
cspvsri3 _ da»davspc2; 
%turn on Content Analyzer% 

cspvs«vscapf _ true; 
%institute the procedure *f ilterproc* as Content 
AnalyzerX 

cspcacod ^ Sfilterproc? 
Xset up for display recreation* 

dpset Cdspjpft curwkrt endfilt endfill5 
If you have edited the filet use the type "dspyes" instead 
of "dspjpf" in your call on "dpset*» 
Other Useful Procedures 

astrucf astr ing) -- given the address of a stringt sets the 
string to upper case* 

f echnoCstid«astr1ng) -- given an stid» appends the statement 
number string to the string variable whose address is passed* 
getsid(stid) — given an stidt returns value of SID «don»t 
forget to add zero to front if converting to a string! 
fechsigCstidtastring) -- given an stidt appends the statement 
signature to the string variable whose address is pessed. 
getdatlastringj -- given the address of a string» appends date 
and time to string. 

grptstCstidl tst id2l — checks that two stid*s specify a legal 
group* returns thew ordered or else an "illegal group* signal 
is generated* 

plxsettstidJ — given an stidt returns the stid of the head 
and of the tail of the plex of which the passed stid Is a 
Riefflbert e»g. first _ plxsetCstid : last) 5 
resetf If ileno) — given the file number of and open filet 
deletes all contents of the file leaving only origin 
statesientt resets date and ident in origin statement Cleaves 
file locked) 

f ilna»(f ilnotastring) •- given the file numbert appends the 
file name fin link foriBat surrounded by angle-brackets <>) to 
string whose address is passed 

pauseCmi lliseconds) — waits the given number of mi llisecondst 
then returns 

settimer Cmi lHsecondstaproctparaiRltparam2tparaBi3tparam4) — 
calls procedure whose address is passedt passing up to four 
parameters to that procedure t after given number of 
milliseconds 5 other code will be executed in the mean time 
Globals of Interest: 

♦initsr* — is the login ident of the person currently using 
the program. 

inptrf -- is incremented every time the user types a <CTRL-o>5 
this can be used as a user program interrupt mechanism! i»e« 
you can set it to at the beginning of the program and then 
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ARSEFUNCTION 
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f % for questions - 
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nflrrsf % reads next char 
gt % reads next char 
tiont % TRUE If next cha 
peatt % TRUE If next cha 
swf % TRUE If next cha 
nflriBt % TRUE If next cha 

g» X TRUE If next cha 

I8f % TRUE If next cha 

aaet % clears the naiie 

% reads next chart 



ur program to see If 


es to abort the 


user types a <CTRL-s>* 


ystems 


rograsis to build a 


LIO support 


lied separately Cby 


EL files. The Load 


will load both at once 


e CHL code Is "ciil** 


subsys** Once loadedt 


as he does coBiBiands In 


a prograiR by copying 


file 


e modified to fit the 


e FILE statements 


quired by the Coinplle 


t are used In the NLS 


ons1 stent use of 


ve been left blank* 


e» proceduret 


y» The last three 


ejsplary* > 


struct % 


returns 0/1 % 


TRUE If space % 


If ca X 


if BUG % 


r Is opt char % 


r Is repeat % 


r Is Y/CA % 


r Is CA/REP EAT/ INSERT 


r Is BUG X 


r Is a number % 


area X 


TRUE If not CA char % 



DECLARE COWHAND yORD 
"BRAUCH* = I t 
"GROUP" = 2 t 
"PLEX" = 5 f 
"STATEHENT" = 4 , 
"CHARACTER" = 5 t 
"COPiTROLCHAR" = fe 
"INVISIBLE" = 7 t 
•LINK" = 8 t 
"DIRECTORY" = 9 t 
"PASSWORD" = 10 t 
•NUHBER" = 11 t 
•TEXT" = 12 t 
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"VISIBLE" = 13 f 
"MORD" = 14 f 
•FILE" = 15 « 
"NEtfFILELIWK" = 16 « 
"OLDFILELINK* = 17 ♦ 
"NAME" = 18 f 
"lOEMT" = 19 ♦ 
"IDENTLIST" = 20 t 
"EDGE" = 21 t 
"HARKER" = 22 t 
"NLS" = 23 t 
•ITEH" = 24 f 
"ITEHNOVS" = 25 ♦ 
"SUCCESSOR" = 26 f 
"PREDECESSOR" = 27 t 
''UP'* = 2B f 
"DOyW" = 29 ♦ 
"HEAD" = 30 « 
"TAIL" = 31 * 
"END" = 32 t 
"BACK" = 33 ♦ 
"NEXT" = 34 ♦ 
"ORIGIN" = 55 f 
"FILERETURM" = 36 , 
•RETURN" = 37 ♦ 
"FILENAME" = 38 t 
"FIRSTNAME" = 39 « 
"NEXTNAME" = 40 t 
"EXTNAHE" = 41 ♦ 
"FIRSTCONTENT" = 42 » 
"NEXTCONTENT" = 43 t 
"FIRSTyORD" = 44 « 
"NEXTyORD" = 45 ♦ 
"DETACHED" = 46 t 
"TTY" = 47 f 
"AUTO" = 48 t 
"CONTINUE" = 49 f 
"ON" = 50 f 
"RECOVER" = 51 t 
"SLINKER" = 52 » 
"UPDATE" = 53 9 
"CLEAR" = 54 t 
"IDENTS" = 55 t 
"FILES" = 56 f 
•DELETE" = 57 ♦ 
"DEFERRED" = 58 « 
"IMMEDIATE" = 59 t 
"NOT" = 60 f 
"PREVENT" = 61 « 
"RESET" = 62 f 
"ARCHIVE" = 63 t 
"SEdUENTIAL" = 64 f 
•TyO" = 65 f 
"JUSTIFIED" = 66 t 
"ASSEMBLER" = 67 » 
"BOTH" = 68 9 
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"UNDELETE" = 69 t 
•FOR" = 70 f 
"STATUS" = 71 t 
"TAPE" = 72 » 
"ACCOUNT" = 73 ♦ 
"NO" = 74 f 
"VERSIONS" = 75 ♦ 
"EXTEPISION" = 76 f 
•DATE* = 77 t 
"CREATION" = 78 ♦ 
"LAST" = 79 t 
"FIRST" =: 80 t 
"READ" = 81 ♦ 
"WRITE" = 82 f 
"OUHP" = 83 t 
"EVERYTHING" ' 84 t 
•LENGTH" r 85 t 
"HISCELLANEOUS" = 86 ♦ 
"ACCESSES" = 87 » 
"PROTECT" = 88 » 
"SIZE" = 89 » 
•TIHE" = 90 « 
"VERBOSE" = 91 , 
"SORT" = 92 * 
"BYTES IZE" - 93 t 
•ARCHIVED" = 94 f 
•ALL" = 95 t 
"MODIFICATIONS" = 96 « 
"UPPER" = 97 ♦ * 
"LOWER" = 98 t 
"MODE" = 99 ♦ 
"SENDHAIL" = 100 f 
•BUSY" = 101 t 
•QUICKPRINT" = 102 f 
"JOURNAL" = 103 t 
"PRINTER" = 104 t 
•COM" = 105 f 
"TERMINAL" = 106 t 
"REMOTE" = 107 « 
"REST" = 108 t 
"CASE" = 109 t 
"CONTENT" = 110 f 
"TEMPORARY" = 111 t 
•VIEUSPECS" = 112 f 
"EXTERNAL" = 113 t 
"TO" = 114 ♦ 
"PRIVATE" = 115 « 
"PUBLIC" = 116 t 
"TENEX" = 117 f 
"ALLOW" = 118 t 
"EXECUTE" =119 t 
"APPEND" = 120 « 
"LIST" = 121 t 
"SET" ' 122 » 
"SELF" = 123 f 
"FORBID" = 124 « 
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"DISK" = 125 f 
•DEFAULT" = 126 t 
«0L0» = 127 t 
•NEW* = 128 f 
"COHPACT" = 129 « 
•RENAME" = 130 t 
"ADD" = 131 9 
"SUBTRACT" = 132 t 
"MULTIPLY" = 133 t 
•DIVIDE" = 134 « 
•RISHT" = 135 f 
"LEFT" =136 9 
•ACTIOI^« = 137 9 
"AUTHORS" = 138 » 
"COMMENT" = 139 « 
"EXPEDITE" = 140 t 
"HAROCOPY" = 141 t 
"IliFORMATIOM" = 142 « 
"INSERT" = 143 9 
"KEYyORDS" = 144 9 
"OBSOLETES" = 145 9 
"RFC" = 146 9 
"SUBCOLLECTIONS" = 147 9 
"TITLE" = 148 9 
"UNRECORDED" = 149 9 
"LIO" = 150 9 
"PROCEDURE" = 151 9 
"SEQGEWERATOR" = 152 9 
•BUFFER" = 153 9 
"NDDT" = 154 9 
"PARSERULE" = 155 9 
•CA" r 156 9 



ft 



CD" = 157 



9 



"RPT" = 158 9 
"BC" = 159 9 



•By" = 


160 


9 




•8S" = 


161 


9 




"LITESC" = 


162 


9 


•IGNORE" = 


163 


9 


•se« = 


164 


9 




• sy" = 


165 


9 




"TAB" = 


: 166 9 





•IHLAC" s 167 9 
«TI" = 168 9 
"NVT" = 169 9 
•EXECUPORT" = 170 
"MENU" = 171 9 
"ONLS" = 172 9 
"TNLS" = 173 9 
"COHHANO" = 174 9 
"RULE" = 175 9 
"SUBSYSTEM" = 176 
•DISPLAY" = 177 9 
"FROZEN" = 178 9 
"HLPCOM" = 179 9 
"PROGRAM" = 180 9 
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«TERSE« = 181 t 

"INDENTING** = 182 t 

••UNIVERSAL" = 185 t 

"ENTRY* = 184 » 

"INCLUDE** = 185 t 

«BOTTOH" = 186 • 

"PAGE* = 187 t 

•OFF* = 188 t 

"FULL" = 189 f 

"PARTIAL" = 190 t 

"AWTIGIPATORY" = 191 t 

"DEHAND" = 192 « 

"FIXED" = 193 f 

"CONTROL" = 194 t 

"CURRENTCONTEXT" = 195 t 

"FEEDBACK" = 196 t 

"HERALD" =: 197 ♦ 

"PRINTOPTIONS" = 198 » 

"PROMPT" = 199 t 

"RECOGI^ITION" = 200 ♦ 

"STARTUP" := 201 t 

•LEVELADJUST" = 202 t 

"REVERSE" = 203 * 

"TEST" = 204 f 

"TASKER" = 205 9 

"LIfiEPROCESSOR" = 206 « 

"CE^JTEH" = 207 f 

"CNTLQ" = 208 ; 
% COMMOH RULES X 

% ENTITY OEFINITIONS % 

editentlty = textent / structure; 
X TEXT ENTITY DEFINITIONS % 

textent = textl / "TEXT" / "LINK"; 

textl = "CHARACTER" / "yORD" / "VISIBLE" / 

"INVISIBLE" / "NUHBER"? 
% STRUCTURE ENTITY DEFINITIONS % 

structure = "STATEMENT" / notst atement » 

notstatement = "GROUP" / "BRANCH" / "PLEX" I 
SUBSYSTEM naflie KEYWORD "NAME" 
INITIALIZATION fnamel = 

* 
COMMAND fr»afire2 - "COMHANOWORD" 

» 
TERMINATION fnameS = 

I 
END. 
FINISH 
FILE Inafse % CLlO.SAVt) TO ( InaiBe.subsys*) % 
% globals % 

Cxname) PROCEDURE % execution procedure % 
XForfflal ParametersX 

Cresult* Xresult records 

parseiBodet Xparsingt backupt cleanup% 

paraiilf lyour first parameter •••% 

para#2« %of course you may have.»»% 

param3)» %0 to 7 of your own pararoetersX 
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%tocalsX 




REF result f paraailt paramZ% param^i 




CASE parsemode OF 




= parsing: 




BESIN 




ewd; 




= backup* = cleanup: 




BEGIN 




END ; 




endcase; 




RETURNC&result); 




END. 




FINISH 




P mi five: Advanced Prograwwing Topics 




Section l: Error Handling — SIGNALS 




Introduction 




yhen an NLS system procedure falls to perforis prope 


rly* it fiiay 


generate an error signal. Every signal has a value 


• Uhen a 


signal Is generated* control Is passed back to the 


last signal 


trap In effect. If no explicit program control sta 


teieent 


(e.g. RETURNt GOTO) is given in that signal trapt a 


new signal 


will be generated. If the error is not dealt witht 


the signal 


will eventually bubble all the way back to the exec 


ution 


routine. The execution routine should always trap 


a signal. 


You may trap signals and regain control by setting 


up t he 


response In advance. 




Trapping Signals 




To trap error signals of any error value: 




QH SIGNAL ELSE statement ; 
E.g. 

ON SIGNAL ELSE 






BEGIN 




disf!iesC2f $string> ? 




return; 




END? 




It is a good idea to set up a signal response before calling 


any NLS systeai procedures. 




Once the signal response is sett it rewalns in effe 


ct through 


the end of the procedure or until it Is changed* ano yill be 


executed whenever a signal is received by that proc 


edure. Any 


subsequent ON SIGNAL statements will at that point 


change the 


signal response Ci.e. only one signal response can 


be in 


effect at any point during procedure execution). 




Only signals generated by procedures below (e.g. ca 


lied by) 


your procedure will be trapped by your procedure's 


signal 


trap. It will not trap signals generated In the &ame 


procedure. 




The signal response Bay be any Cblock of) LIO state went Cs) • 


It will be executed* then 




- if you have an explicit program control statement 


CRETURNt GOTO* EXIT LOOP)* control will be passe 


d 


accordingly and the signal will stop there* or 




- if the signal trap Includes no explicit program control 


statement* another signal of the same value will 


be 


generated* and control will pass upward through 


the stack 
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of procedures called until it encounters another signal 

t r ap • 
h RETURN will return control to the procedure which called the 
one which Intercepted the signal <not the one which generated 
1t>» 

Thust 1f you wish to resuraie control In the current procedure* 
the signal trap will have to end with a GOTO statement 
pointing to an appropriately labeled statement* This Is one 
of the few places where a GOTO Is really necessary* 
If the signal trap applies to a loop* an EXIT LOOP cr REPEAT 
LOOP Is a valid signal program control statement* 
Trapping Signals In Execution Routines 

If a signal bubbles up through the execution routine to the 
cofRuiand parser Cin a coiajBand In an attachable subsystem^* the 
results may be unpredictable* Execution routines should 
always Include signal traps* 

A RETURNCFALSE) will shift CML Into backup fnode* It will back 
up to before the last set of CWL alternatives (not necessarily 
equivalent to the last user Input elewentJ* and then shift 
back Into parsing fnode* (This rsay Istply backing all the way 
through the coffiwand* 1*e* aborting the command*! 
The procedure "abort sub system" may be useful In this context* 
It will shift the GOffiwand parser Into backup aode and abort 
the current comaand* Then It will execute a Quit C f rom the 
current subsystem) and return the user to the previously used 
subsystein* It should be passed the address of an error string 
to be displayed* E*g* 

ON SIGNAL ELSE abortsubsystefii( $*Error In xprocedure* ..» J I 
or 

ON SIGNAL ELSE abortsubsysteist sysiRsgJ I 
I see "Specific Signals") 
Cancelling Signal Traps 

After program execution sets up a signal response* the 
following statement will cancel It so that thereafter a signal 
will Just bubble on up: 

ON SIGNAL ELSE NULL 5 
or just 

ON SIGNAL ELSE ; 
It stay be subsequently reset by execution of another ON SIGNAL 
statement* 
Specific Signals 

When a signal Is generated* the NLS system global variable 
■sysgni* Is given a specific value (the value of the signal)* 
Each value represents a certain type of error* Also the 
system global variable "sysmsg" Is given the address of a 
string which holds an error message* 

The above constructions react to any signal* no matter what 
Its value may be* The ON SIGNAL statement can be used much 
like a CASE statement (comparing cases to the global sysgni) 
If you wish to trap specific signals: 

ON SIGNAL 

^constant: statement! 
=constant: statement? 



ELSE statement! 



E.< 
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ON SIGNAL 

=ofilerrI %open file error! 
BEGIN 
IF sysiBsg THEN d1sroesC2«sysiBsgM 

return; 
end; 

ELSE Xany other error slgnaLX 
BEGIN 
d1sfBesC2»$"Error") « 

return; 
end; 
The current signal constants can be found In <NLSfBCONSTt>» 
The coMBon reason for using this specific signal treatment 1s 
when you call a procedure which you know will generate a 
certain signal value under certain conditions* In such a 
caset you can learn the signal constant of concern froR» the 
SIGNAL statement which generates It* 
Generating Signals 

You way generate a SIGNAL In a procedure by the statement: 

SIGNAL (valuet astring) ; 
where value Is the value of the signal (perhaps a systeiB 
global) and astring Is the address of a string holding the 
error message* If the second parameter Is OBtlttedt It will be 
assumed to be zero and no message will be printed* The first 
parameter Is mandatory; every signal niust have a value* 
Examples. 

SIGNAL Cofllerrt S»Couldn»t open your file*") » 
SIGNAL (2) ; 
Another way to generate a SIGNAL is by calling the procedure 
err<errno) 

It will generate a SIGNAL of the value "errslg* Ca system 
glpbal) andi will set up a message depending on the value 
you pass for errno* errno may be any of the following: 

1 — »F1te copy falls"; 

2 — *Open scratch falls*; 

3 — "Cannot load program^* 

4 «- "I/O Error"; 

5 — "Exceed capacity"; 

6 — "Bad file block"; 

7 — "Not Implemented" 

If you pass It the address of a string as the error 
number* It will signal using that address for sysmsg* 
and that string will be printed. 
By allowing err to generate all the signals* you will find 
It easy to freeze execution upon an error condition while 
debugging using NODT* as described In the next section Cby 
setting a breakpoint at erri* 

Be careful not to call err and then trap Its SIGfilAL In that 
same procedure* You might say: 
ON SIGNAL 

=errs1g: NULL; 
ELSE * • * 
Section 2: NDDT Debugging 
Introduction 

Debugging Is the process of finding the errors In a program* 
Once the problem 1s located* you may correct It In the source 
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code {^JLS file) and recoiftpHe. 

NLS includes a debugging tool called NDDTi for *WLS Oynarolc 
Debugging Technique." WDDT allows you to examine the state of 
your progran during or after running 1t C1»e« using the 
command or filter). This section describes the capabilities 
of I^DDT. 
Accessing NDDT 

To Riake WDOT available frofR NLSt you must execute the coBinand 
In the PROGRAMS subsystem: 

Set Hddt Ccontrol-h) OK 
This adds the progra* NDDT to your user programs buffer. 
Thereafter f whenever you type a <CTRL-h>» NLS will ImiRedlately 
be interrupted (be it In a waiting or running state) and you 
will enter NDDT* NDDT will respond with its cosjsiand hearaldt 
a right angle-bracket (>>§ indicating that NDDT Is ready to 
accept a command. 

NDDT commands are specified by typing the first character 

of the coifjiBand word. 
You may continue with MLS Cfpom the point where it was 
interrupted) with the NDDT command: 

Continue OK 
You Biay continue NLS froa a specific Instruction address with 
the NDDT command: 

Goto ADDRESS OK 
NDDT Address Expressions 

Everything stored in the machine (Instructions and variables) 

has an address* its location within the computer's iriemory. An 

address is an octal tbase-eight) number* 

The na«e of a procedure or of a nained LIO statement way be 

used instead of a nusiber. It represents the octal location of 

the named stateatent or of the first instruction of the 

procedure. 

Addresses (syiBbols or numbers) way be co«ib1ned» to evaluate to 

sonre location. An expression concatenated with the following 

operators will be evaluated frois left to right fno 

hierarchical ordering) to a single value: 

<SP> same as + 

* 
/ 
Thusf a syibol siiay be followed by a space Cor plus-sign) and 
then an octal nufRber. The number is added to the location 
represented by the symbol. 
Single-Word Variables 

Often* programmers wish to examine or modify the cortents of a 
single word at a given location. The NDDT Show command prints 
the contents of the word at that address. 
Show Location ADDRESS OK 

where address is an address expression as defined above or 
one of the following: 
** — preceding entity 
<LF> -- next entity 
Next — next entity 

<TAB> ■ — entity whose address is the content cf current 
location 
NDDT fRalntains some address as your current location» and the 
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Show coBiffiand sets this location to the one It ejcamlnes* If 
you do not specify an address In a show cosunandt the current 
location Is assufsed» 

NDDT can print the contents In three ways: as a symbol 
followed by a number (to be added to the syuJbol location)* as 
a single number* or as text* The default printout siode Is 
symbolic • The printout «ode «ay optionally be changed In a 
Show cofRmand* The new printout mode resialns In effect until 
subsequently changed* 

Show Location ADDRESS <CTRL-b> PRINTHOOE OK 
where PRINTHODE Is one of the following: 
Numeric 
Symbolic 
Text 
A fast way to do the saaie thing Is provided with the Value 
cosifnand: 

Value of ADDRESS OK 

or 
Value of ADDRESS <CTRL-b> PRIflTHOOE OK 
You may print and then replace the value In a word with the 
Show command: 

Show Location ADDRESS _ EXP OK 

or 
Show Location ADDRESS <CTRL-b> PRINTMOOE _ EKP OK 
where EXP Is an expression whose value will replace the old 
value of the given location* In addition to the address 
expressions discussed above* you may use the forts: 
Vdluel*tvalue2 

where "valuel" Is a standard expression which will be 
put In the left half of the word* and '•value2» Is an 
expression which will be put In the right half* 
String Variables 

The contents of a string variable may be examined and modified 
as well as simple variables* using the command: 

Show String ADDRESS OK 
Strings are always printed In text printout mode* 
You may print and then replace the string with the Show 
command : 

Show String ADDRESS _ STR OK 

where STR Is a literal string which you type In* 
Records 

To work with LI records* you must first set the NDDT record 
pointer to the first word of an LID record definition* with 
the command: 

Record pointer set to: SYMBOL OK 

where SYMBOL Is the name of some LIO record* Note that It 
may be necessary to use the MARK command (described belowl 
to make local records known to the NDDT system* 
This Is equivalent to the command: 

Show Location RP _ SYMBOL OK 
You may then examine all the fields of any record with the 
command : 

Show Record ADDRESS OK 

or 
Show Record ADDRESS <CTRL-b> PRINTMOOE OK 
You may examine and optionally change a single field within a 
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record yith the Show Location comBiandf substituting 

ADDRESS.FIELO for ADDRESS* 

You rBay replace each field In a record with the coaffiand: 

Show Record ADDRESS _ 

The name of each field Is then printed and a new value may 

be typed Int terminated by a Coaisand Accept* Typing only a 

Coitmand Accept will advance to the next field of the record 

without modifying the last field* 
Built in NDDT symbols 

A number of symbols are built 1n to NDDT anti may be used 1n 
address expressions* yhen they are usedt PRINTHOOE will be 
Ignoredf since the printout roode Is predefined for each of 
these synjbols* 
Built In Locations! Registers 

Al — register Al 

A2 -- register A2 

A3 — register A3 

A4 -- register A4 

Rl — register Rl 

R2 -- register R2 

R3 — register R3 

R4 — register R4 
Built In Locations* Frawe 

When a procedure Is cat led t a "frase* is added to the 

stack* It Includes a word (holding the return location of 

that procedure In the right half) followed by all the 

parametersf then all the locals* Some predefined symbols 

allow you access the current or any previous frames and the 

InforiRatlon In them* 

n — contains address of current frasie 

HARK — contains address of previous frarae 

RET -• return location In current fra«e 

RP -- address of record definition of last field used 

S *- contains address of top of stack Clast LOCAL word* or 

whatever) 

SIG --^ current fraaie signal location 
Built in Records 

BASE — first frasie In procedure stack 

FRAME -- current frane description 

F — same as FRAME 

LOCALS — current frame LOCALS 

L— same as LOCALS 

RECP — ^description of current record 

R *- sawe as RECP 

PARMS — current frasie paraaieters 

P — same as FARMS 

TOP -- description of top frame In procedure stack 
Control Switches 

EC -- Current symbol escape character (»l 

RNAMES --If FALSE suppresses printing of record field 

names 

SF — If FALSE disables these MOOT built In symbols 
Special character commands 

The special character commands are provided for comiponly used 
functions* All but = are essentially subcommands of the SHOy 
command and are processed exactly as If they had been preceded 
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by the cofRmand word Show* 

= — Show current location in nuierlc typout without 

changing the current printing mode 

_ — Assign 3 value to current location 

^ -- Show previous location 

LF -- Show next location 

TAB -- Show location addressed by current location 
Traces and Breakpoints 

If you set a "trace" at a locatlont the system will print that 
address every tlsie that Instruction Is executed. Execution 
will not be Interrupted* You may set a trace with the 
cofflRiand: 

Trace location ADDRESS OK 
If you set a breakpoint at a locatlont a <CTRt-h> will 
autoisatlcally be executed Just before the given Instruction 
(causing you to Interrupt execution and enter NODT> • This 
allows you to Interrupt execution of your prograiR at a given 
point and examine and change the state of the syste»» A 
breakpoint may be set with the coiRwand: 

Breakpoint Set ADDRESS OK 
Each trace and breakpoint Is assigned a numbert beginning with 
zero* when It Is set» You may cancel a trace or breakpoint 
using this number or using the address to which 1t Is set: 

Breakpoint Clear NUMBER OK 
or 

Breakpoint Clear ADDRESS OK 
You may cancel all traces and breakpoints that you have set 
with the comifiand: 

Breakpoint Clear All OK 
You fsiay list a trace or breakpoint of a given nuiiber and the 
location to which It Is set with the command: 

Breakpoint Print NUHBER OK 
You way list all traces and breakpoints? their nuwberst and 
their locations with the cosiiRand: 

Breakpoint Print OK 
A breakpoint way replace a previous trace or breakpoint Cnew 
addressi same number > with the cowaiandt 

Breakpoint Set ADDRESS <CTRL-b> Replaces breakpoint NUWBER 

OK 
A breakpoint enay be set so that It only Interrupts If a 
comparison between location and a given constant Is true? with 
the following command: 

Breakpoint Set ADDRESS <CTRL-b> Test ADDRESS REtCP CONSTANT 

OK 

where ADDRESS Is the location of the word to be compared* 
RELOP Is one of thfe following: =»<><=:>= 
COf^STANT Is an expression with a value. 
A breakpoint »ay be set so that It only Interrupts 1f a 
procedure Is called and returns truet with the following 
coBtfRand: 

Breakpoint Set ADDRESS <CTRL-b> Call PROCEDUREfsJAKE OK 
LIO Procedures 

You may call an LIO procedure from WOOT with the corraiand: 

Procedure Call PROCEOURENAHE OK 
If the procedure requires parameters* you must list theis In 
parentheses* separated by cofRBsas* after the name of the 
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proceciure: 

Procedure Call PROCEDUREMAHE Cparawlt parafR2f •••> OK 
One strtn§t enclosed in quotes* may be included in the 
parameter list » e*g«: 

Procedure Call PROCEDURCNAHE ("literal"* par3iB2» ...> OK 
The return valueCs) of a procedure call will be typed out» 
NDOT allows you to replace an existing procedure with a new 
procedure, yhenever the old procedure is called anywhere in 
the systefBf the new procedure will be called instead* The new 
procedure will be passed the saate paraBeters as were passed to 
the old* This replacement can be done with the coroaiand: 

Procedure Replace OLDNAHE OK NEVtylAHE OK 
The name of the procedure which was replaced is saved so that 
it may be restored* The replacement nay be cancelled with the 
coiBBand: 

Procedure Back up to OLDNAHE OK 
Syisbols 

The system maintains a table of syntboi naaics and the addresses 
which they represent* yhen a user program is loaded* its 
symbols are added to the syisbol table* Thus* (in addition to 
systesi globals) the table is composed of blocks* one for each 
progra«* 

Each block is refered to by the Cuniquel naae of the 
prograiR* (This is why the CML and SUBSYS parts of a user 
attachable subsystesi jsust have different names in the FILE 
stateffient*) The list of blocks (prograwsJ is called the 
*i!jark stack* ■ Locals as well as globals are recognized by 
MOOT for only those user prograns in the «ark stack* 
You iBay list the nanes of the blocks currently in the mark 
stack with the coiBBiand: 

Wark symbol table: Print contents of stack OK 
A block may be deleted from the nark stack Cthe symbols remain 
in the symbol table* but they are not recognized by NDDTJ with 
the commands 

«ark symbol table: Clear block PROGRAKfyAHE OK 
A block may be reinstated to the mark stack with the command: 

Mark symbol table: Set at PR06RAHNAHE OK 
A new Cemptyl block may be added to the mark stack with the 
command: 

Hark symbol table: Set at UEyBLOCKNAWE OK 
If there is at least one block in the mark stack* a new symbol 
representing some address may be created with the ccmmand: 
Define New SYH80LNAME OK ADDRESS OK 

Symbols defined with this command have a global scope* and 
may be used to satisfy external references in LlC user 
programs subsequently compiled* 
Any symbol within a block listed in the mark stack may be 
redefined to represent a different address with the command: 

Define Old SYHBOLNAHE OK ADDRESS OK 
If you wish to replace an existing routine by a new version of 
the same routine* some method of distinguishing between new 
and old occurrences of the same symbol is required* Any 
symbol preceded by a semicolon C«> refers to the olc 
occurrence of the symbol* CThe semicolon has the effect of 
disabling the symbol table marking mechanism for the given 
symbol* causing it to be identified in the "old* section of 
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the symbol table.) 

For example* suppose an existing routine na«ed TEST 1s to 
be replaced by a new version of the saRte routine which you 
have just coaiplled Chence Is In the mark stack). The NOOT 
Procedure Replace cowwand can be used as follows: 
Procedure Replace I TEST OK TEST OK 
Scanning for Content 

You may search a set of words for a specific content with the 
coiRirtand: 

Find content: CONTENT OK aiasked by: OK lower address: 
STARTAODRESS OK upper address: ENiDAODRESS OK OK 
The content of every word In the specified range will be 
compared to CONTENT* COMTEMT way be of the f oris of an address 
or a PDPIO machine Instruction. The address and content of 
each word which satches will be printed. (Wote that the 
"fflasked by" field was Ignored.) 

If you wish only to compare certain bits In each word to 
corresponding bits In CONTENT* you may specify a mask. A mask 
Is a number (of the address forra). Only those bit positions 
In which the mask has a one will be conspared. tif the mask Is 
not specified* all ones will be assufiied and the entire word 
will be compared.) 

Find content: CONTENT OK masked by: ¥i^SK OK lower address: 
STARTADDRESS OK upper address: ENDADDRESS OK OK 
HASK may also be of either the ADDRESS form or the PDPIO 
instruction form. 

Section 5: yrlting CML Parsefunct Ions 

Parsef unctions 

Functions which are declared with the PARSEFUNCTION attribute 
1n cut are assumed to be 110 procedures which are designed to 
be parsing functions. They are used to examine the user»s 
Input. They are called In "parsehelp* mode before being 
called In "parsing" mode, yhen so called* they are passed the 
address of a string as a third Implicit argument. The 
parsefunct 1on routine should fill that string with the 
appropriate prompt characters which tell what the parsing 
function Is looking for. 

yhen the user Is faced with alternatives which Include a 
parsefunctlon* the parsefunctlon will be called In parsemode 
"parseqmark" for the string to Include In the quest lonmark 
display. This string must be no greater than 24 characters. 

Sample Interpreter Parsefunctlon Routine 

Assume that In some command we want the typein of a number to 
appear as an alternative to some set of keywords. ye can 
accomplish this by defining a parsefunctlon Ccall It looknum) 
which looks at the next Input character and succeeds If the 
next character 1s a digit and falls otherwise. If we write 
this function as the first alternative In some command* then 
control will pass from the Interpreter to the parsefunctlon 
before It passes to the keyword Interpreter. 
Suppose our command looks like: 
COMMAND sample = "INSERT" 

( looknum () < "number "> ent _ #»NUHBER" 

/ ent _ ("TEXT»/"LINK") ) 

% entity now contains an entity type C NUMBER* TEXT* or 
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LIfilK >• We now use the LSEL function to get a selection 
of this type % 

source _ LSELCentJ 
COMFIRH 

X Insert Cent* source) * 
The parsef unction Looknuro which Is called by the interpreter 
both when prompting the user and also during the actual parse 
of the coraffiand» 

(looknuRil PROCEDURE % looks at the next Input character* 
If It Is a digit f then return TRUEt else return FALSE % 
% FORHAL ARGUMENTS % 

Cresultt % address of the result record X 
parsewodet % parsing mode of the Interpreter % 
strlngll % address of prompting string % 
REF resultt string* 
CASE parseaiode OF 
= parsing: 

CASE lookcC) OF lvalue of next character In Input 
bufferX 

IN C*Of •93: MULL ; 
ENDCASE RETURN(FALSE> ; 
= parsehelp: %supply string for promptX 

♦string* _ "NUH:" I 
= parseq»ark: %supply string for guest Ion «ark % 
♦string* _ **Nuiaber* i 

endcase; 

RETURN f&resulti; 
END. 

Section 4: Calculator Capabilities 
Introduction 

LIO arithmetic can only work with Integers. The CALCULATOR 
subsystem holds a numbers of procedures which the user 
programsier may call to do double-^preclslon floating point 
arlthflietic* Floating point numbers are stored In two-word 
arraysf which the user prograiRfRer Bust declare. All 
CALCULATOR routines work with these two word arrays • 
Converting String to Double-Precision Floating Point 

A nufltber In a string variable way be converted to a floating 
point array with the procedure: 

nfloat (astringt awordlt aword2) 

where astring Is the address of a string holding the 

nusbert 

awordl Is the address of the first word of the array* 
and 

aword2 Is the address of the second word of the 
array. 
The nuwber In the string may hold a declRtal point* and ssay be 
preceded by a minus-sign (-)• Other characters €e#g» a dollar 
signl may precede the first character of the number Ca digit* 
minus sign* or decimal)? they will be Ignored. 
Converting Floating Point to String 

The two word array may be converted back to a string with the 
procedure: 

qfloutp (avar* astring* format) 
where 
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avar is the address of the (first word of the I array 

holding the floating point nuiRbert and 

astrino is the address of a string variable in which the 

text of the nyaiber is to be placed; 

the third parameter is ignored t so just pass zero. 
The format of the string is dictated by the global variable 
*dfQutfi!»* The following fields apply to this global Cdefault 
values are in square brackets!: 

fldl — characters to the left of the decimal CI 01 

fld2 — characters to the right of the decietal C 23 

f ld3 — characters in exponent field C03 

round — nymber of significant digits to round to C123 

round must be less than or equal to fldl + fld2 fldl *- fld2 

pust be less than or equal to 12 

oflo ~- go to exponent notation if left-of~deci»al too big 

CO 3 

exsign — if a positive exponentt use first character of 

exponent field for: C03 

— first digit of exponent 

1 — «*• 

2 -- a space 

exp2 — prefix on exponent: CO 3 

— no exponent 

1 — «E» 

2 — *D" 

dpi — print decimal point switch <0=Offf l=On) £13 

dig — print at least one digit to left of decimal (0 if 

necessary) (O=0fff l=On> C13 

Just — justify number within space of three fields: C13 

— right justify by adding spaces tc left 

you must also set the 
global "calflg" to TRUE 

1 — right justify by adding "O^s 

2 — right justify by adding **»s 

3 •- left justify by adding spaces to right 

you iRust also set the 

global «calflg» to FALSE 
sign — if a positive nu»bert use first character of field 
1 for: CO 3 

— first digit of number 

1 --" a space 

2 — "♦• 

Additionallyt if the global "cacflg" is TRUE* the number will 
be formatted with coiRBtas* 
Calculations with Foating Point 

The following procedures do floating point calculations on the 
two-word arrays described above* All of the following 
procedures require as parameters the address of the tfirst 
word of the) arrays. 

qcaddCatb) -- a _ a ♦ b 

qcsubCatb) -- a _ a - b 

qcmultCat b) -- a _ a * b 

qcdivCatb) -•- a _ a / b 

qcdivwCa»btc) — ^ c _ a / b 

qcnegCa) — a _ -a 
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Section 5: Fields and Records 
Introduction 

A set of bits within a word can be used without affecting the 
rest of the word* (On the POP-lOt words are 36-b1ts long*) A 
contiguous set of bits within a word Is called a field* 
Fields allow more efficient use of storage. 

Once a field Is defined* you aiay apply It to any word 

Cvar1able>» It will refer to the defined set of bits 1n 

that word Ce«g» the field "RH" refers to the right-most 18 

bits of whatever word It irrodlfles)* 
You Riay assign a nuaber to or iron a field by following the 
variable name with a period C«>» then the name of the field: 

var» field 

E.g. stid.stpsid _ origin ? 
Hany fields are defined in the NLS systei* and »ay be used by 
user prografBisers. Sofae have been mentioned In preceding 
sections; others may be found In the NLS source code. 
Declaring Records 

Records are always defined globally. Record definitions are% 

like global declarations* put outside of procedures within LIO 

files. 

A record definition defines a series of fields* with the 

length Cnumber of bits) specified for each field: 

RECORD fleldlC length!* f1eld2C length 3* ... ; 
The fields are allocated frors right to left within the word. 

E.g. the record definition: 

RECORD r1ghtE183* leftCl73 ; 

would define two fields. The field "right" refers to the 

right-most 18 bits of the word. The field "left" refers to 

the next 17 bits to the left of the field "right." <The 

left-most bit Is not used In this example.) 
A RECORD definition may specify any number of fields* If a 
field Is defined to be too large to fit In the rewalnlng bits 
of the current word* It Is autoaiatlcally defined to represent 
the first field in the next word. I.e. this and subsequent 
fields are defined from the ripht of the next word. This can 
extend through any nunber of words. 

E.g. the RECORD definition: 

RECORD fieldlC183* f1eld2C103* f1eld3tl83» f1eld4C363 ; 

would define the fields as follows: 
fleldl — right half of word 

f1eld2 -- right-most 10 bits in left half of word 
fields — right half of next word 
f1eld4 -- entire third word Ci.e* wordE2 3) 

Of course when using fields that refer to subsequent words* 

you must be sure that you are operating on arrays of the 

appropriate size. 
Declaring Fields 

Although you can declare single fields as described here* the 

practice 1s liflilted. tit Is useful In aanipulatlng byte 

pointers.) User prograiBBiers should use RECORD definitions 

Instead. 

A single field Hiay be defined with the declaration: 

DECLARE FIELD nawe= taddress* size : position! I 

where 

address is the address of the word to which the field 
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refers* 

size Is the number of bits In the fleidt an4 
position 1s the number of bits left to the right of the 
field. 
In an asslgniBentt the address of the word referenced Is kept 
in a reglstert named "rp*" It way be used as an Index by 
placing It In parentheses* Thus a FIELD declaration refering 
to the right half of a word Is: 

DECLARE FIELD r1ght=CCrp)f 18:03 ; 
The left half of the next word could be defined: 

DECLARE FIELD left=Il<rp)t 18:183 ; 
The address Is held In the right half of a byte pointer* You 
may declare a field with zero as the address* then assign the 
field definition plus an address to set up a byte pointer: 

DECLARE FIELD r1ght=tO» 18:03 ; 
then 

bytepolnter _ right ♦ Svarlable » 
A FIELD declaration may be external as well as global: 

DECLARE EXTERNAL FIELD name = Caddress* size : pcs1t1on3 ♦ 
Section 6: Stacks and Rings 
Declaring Stacks and Rings 

Stacks and rings are allocated series of words of storage* A 

stack or ring Is defined to hold a given number of records! 

each record may be a single or a defined number of words* You 

may "push* records onto the stack or ring and then *pop" thep 

off* as described here* 

A stack may be declared Cat the global level) with the LIO 

declaration: 

DECLARE STACK stacknameCs 1ze3 ♦ 

where size 1s the nuuber of one-word records In the stack* 
You ^ay work with records of more than one word with the stack 
declaration: 

DECLARE STACK st acknaffieC s 1 2e»recs1 ze 3 ; 

where recsize Is the nusiber of words In each record* All 

records In a stack must be the same size* 
Like other declarations* any nuBiber of stacks May be declared 
with the safse statement: 

DECLARE STACK stacknameEs 1ze3« stackna8ieEsl2e*recsl2e3» 

• • • * 
Stacks may be declared as external to the program: 

DECLARE EXTERPIAL STACK st acknaweC s1ze*recs1ze 3* *••; 
Ring declarations are Identical* with the word "RiftIG* 
substituted for "STACK** E*g*: 

DECLARE RING r 1ngnaBeEs1ze3* r 1ngna»eCs1 ze«recs1 zel* ••• ♦ 

DECLARE EXTERNAL RING rlngnasieCsl ze»recs I2e3« ***♦ 
Initializing Stacks and Rings 

Before It Is used* a stack or ring must be Initialized C1*e* 
cleaned up>» with the LIO statement: 

RESET stackname I 
or 

RESET rlngnane » 
The storage can then be considered empty* The RESET statement 
can be used whenever you wish to clean up the stack or r1ng» 
Using Stacks and Rings 

You may add a record to the top of the stack or ring with the 
LIO statement: 
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PUSH address OW stackname » 

where address Is the address of the first word C perhaps the 

single word) of the record to be added to the stack* 

-If you try to add more elements than the stack can holdt a 

SIGNAL will be generated* 

-If you try to add more elements than the ring can holdt 

records will be replacedt starting froui the bottcm Cthe 

first record pushed on)* 
You may remove a record froig the stack or ring? and optionally 
assign It to a record variable Ca simple variable or array of 
the appropriate size) with the LIO statement: 

POP stacknaroe ; 
or 

POP stacknanie TO address 5 

where address Is the address of the first word t perhaps the 

single word) of the record to receive the record frosi the 

stack* 

-If you try to reisove more eleR?ents than the stack 

currently holds* a SIGNAL will be generated* 

-If you try to remove luore eleRtents than the ring currently 

holdsf records will fee reread* starting from the top* This 

should be avoided* If you did not previously f1 II the 

ring* this top record will hold garbage* 
You may read the first word of the record at the top of the 
stack or ring Cwlthout affecting the stack or ring) as an 
expression by enclosing the na«je In square-brackets: 

Cstackna^e3 

The second word (the one below that one the stack) way be 

read as tstacknaaie - 13* and so on* 
E*g* 

var _ CstacknafBel » 
To use stacks and rings* one usually must keep track of how 
ffiany records are currently on the storage* Thus* you probably 
will need to maintain a count In a simple variable In parallel 
to use of the stack or ring* 
Section 7: Using the Sequence Generator 
Introduction 

The Sequence Generator is used by a number of NLS ccmmands 
which require a series of statements from an WLS file* A 
procedure may open a sequence holding a number of statements; 
the Sequence Generator then passes those statements back* one 
at a time* every time 1t Is called* 

The Sequence Generator considers vieuspecs In choosing which 
statements to return* e.g* level truncation* If viewspec 1 or 
k Is on* It may call a Content Analyzer program before 
returning the statement* This allows a great deal of 
flexibility In working with a series of statements* 
Co-Routine Effect 

Once the Sequence Generator decides to return a statement Cor 
string)* It calls a mechanism which returns control to the 
procedure that called the Sequence Generator* Thus control 
will return directly to that calling procedure* ever from 
other procedures the Sequence Generator has called* 1*e* even 
If the return mechanism was called from a procedure called by 
the Sequence Generator* 
When the Sequence Generator 1s called the next time* It passes 
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control to the Instruction after the one which called the 
return fRechanisiJ* I«e» 1t continues right where It left off» 
Thusf the Sequence Generator raay call a Content Analyzer 
program which may return control directly to the procedure 
which called the Seciuence Generator* The next time the 
Sequence Generator Is calledt execution will begin In the 
ffilddle of that Content Analyzer prograw (which may later 
return through the noraial RETURN statesjent to the Sequence 
Generator)* <Thust the Sequence Generator Is behaving like a 
co-routine to the calling procedure*> 

Calling Procedure Sequence Generator Content Analyzer 

X • • • 

2 • • • 

3 seqgen(Ssw> >>-> 1 ••• 



2 



• • • 



3 CA filter »- — > 1 ••♦ 

2 • • • 

4 ••• < ^- ^--««*— «-«.—— ™—<< 3 return inechanlssi 

5 #• • 

3 seqgenCSsw) »-—-----■---.--«-——> 4 ••• 

5 • • • 

4 ••• <— — — — -<< 6 normal return 

5 • • • 

7 ••• <-«™— — << 6 return fsechanlsw 
Sequence york Area 

yhen a Content Analyzer program Is called by the Sequence 
Generatort one paraieter Is passedt the address of an array 
called the "sequence work area** This array* although Ignored 
by iRost Content Analyzer prograsst holds a great deal of 
useful Inf orfisat Ion* If the Content Analyzer procedure 
receives this address as a pararaeter* and then REFs 1t» It »ay 
refer to the following fields In the sequence work area (see 
<NLStBRECORDSf seqr> for entire record declaration): 

swstid — stid of current statement or string In sequence 

swcstid — stid of current real STATEMENT In sequence (even 

If swstid points to a string) 

swlbstld — stid of statement heading last branch In 

sequence 

swclvl — level of current statement In sequence 

swslvl -•► level of first stateaient In sequence 

swvspec — first word of viewspecs for sequence 

swvsp2 — second word of viewspecs for sequence 

swusqcod — address of user Sequence Generator procedure 

for sequence 

swcacode — address of Content Analyzer procedure for 

sequence 

swkflg — FALSE when sequence Is openedt TRUE once 

something has been returned by sequence 
Displaying Strings 

You Riay call the return mechanlsw from Content Analyzer 
programs while causing the Sequence Generator to Inject a 
string in the sequence* Under the normal c Ircusistance* where 
the sequence Is being used to put up a display or print a file 
or to do filtered editing* this allows you to Infect a string 
Into the output* Thus you may receive a stateinent* reformat 
It into a string (without editing the statement Itself) ♦ and 
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then display the string. 

The following procedure Injects a string In the sequencet then 
returns to the procedure that called the Sequence Generator: 
send Cswt astring) ; 

where sw Is the address of the sequence work area» and 
astring Is the address of the string. CRefnember t if you 
REFed the parameter holding the address of the sequence 
work areat use the ampersand {&) construct when passing 1t 
to send*) 
Note that the co-routine effect will cause execution to pick 
up right where It left off when the Sequence Generator Is 
called for the next statement. Thus* execution will begin 
just after the send. If you then RETURN a value of TRUEt the 
statesient Itself will ALSO be displayed. Host applications of 
send will RETURNCFALSE* iBiJuedlately after the call on send. 
An example of a Content Analyzer program using sendO to show 
only the first line of each statement: 

Cf1rstl1ne> PROCEDURE Csw) t Xcontent analyzer filter to 
display only first t1nes% 
tOCAL TEXT POINTER ptr t 
REF sw ; 

Xto hold address of sequence work areaX 
%set pointer at end of first I1ne% 
CASE READC OF 

= ENDCHR: FIND ''ptr I 
= EOL: FIND -'ptr _ptr ; 
EfJOCASE REPEAT CASE; 
Xput first line In global strlngX 

*dspstr* _ SFCptrl ptr I 
%1nject string Into sequenceX 

send {&SW* Sdspstrl ? 
%so statement won*t also be d1splayed% 

RETURN (FALSE) ? 
END. 
Using Sequences 

You Biay open and use your own sequences In attachable 
subsystems. This may be useful when you wish to process a 
series of stateroents* perhaps only those passing certain 
requirements (e^g. level or a Content f^nalyzer filter). 
To open a sequencet you should have declared and REFed a 
variable to hold the address of the sequence work area that 
will be reserved for your sequence. The procedure which opens 
the sequence returns this address* 

8.SW ^ openseqCstldl* st1d2t vspecl* vspec2» seqproct 

caproc); 

where 

stldl and st1d2 are two stids dellnlating a group In an 
NLS file that will be the source of the stateiBents In 
the sequence. They way be the same (for a branch). The 
Sequence Generator Ignores the branch only and plex only 
viewspecs. 

To get st1d2» the procedure "seqend* may be useful* 
Given stldl and the two viewspec wordst It checks the 
branch-only and plex-only viewspecs and returns the 
appropriate slid for st1d2. E.g.: 

&sw _ openseq (stldlt seqendlst Idlivspe cltvspec2) t 
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vspecl, vspec2f seqproct caprocJ* 
vspecl and vspec2 are two words holciing the viewspecs 
for the sequence. There a a nusiber of predefined fields 
which allow you to set bits within these words* (See 
Part Fourt Section #•> Of particular Interest to the 
Sequence Generator are the level truncation (not the 
line truncation! and the Content Analyzer vie wspecs. 
seqproc Is the address of the Sequence Generator routine 
to be used. If you pass zerot the NLS standard Sequence 
Generator will be used. (User Sequence Generators are 
not described here.> 

caproc Is the address of a Content Analyzer procedure to 
be used If needed by the sequence las specified In the 
viewspecs). If none Is needed* you aiay pass zero. 
Passing the address of a sequence Is In effect 
Instituting that procedure for that sequence. The 
address of the currently Instituted procedure may be 
gotten from the display area descriptor » as described In 
Part Four, Section 4. 
A call on the procedure "seqgen* will Increment the fields 1n 
the sequence work area to the next statement (or string) In 
the sequence; It will return the first statement In the 
sequence the first time It Is called. You fitust pass It the 
address of a sequence work area* e.g.: 
seqgen (&sw) ; 

seqgen returns the new swstid field of the sequence* or 
endfll If there are no more statements In the sequence. 
You may then refer to the fields In the sequence work area 
for Inforwatlon about that statement ♦ e.g.: 

sw.swstid — stid of current item 1n sequence 
sw.swclvl — level of current IteiR In sequence 
yhen you are done with a sequence, you must close 1 t by 
calling the procedure "closeseq" with the adddress of the 
sequence work area* e.g.: 

closeseq(&sw> » 
A typical use of the Sequence Generator fRight be as follows: 
% set up sequence % 

% set up view specs % 

Xget adress of display area descriptor? da Is REFed 
simple var lab I e% 
Ma _ Idad ? 
%get current viewspecsl vspec Is LOCAL two-word 
arrayJK 

vspec _ da.davspec ? 
vspecClJ _ da.davspc2 ; 
%turn on Content Analyzer for this sequenced 
vspec. vscapf ^ TRUE » 
%openseq with "proc* as Content Analyzer filter, returns 
the address of sequence work areal sw Is REFec sifuple 
variable^ 

Ssw _ openseq(sourcest Id, sourcestid, vspec, 
vspecClIf da.dausqcod, Sproc)* 
01^ SIGWAL ELSE closeseq (&sw ) » 
% loop through sequence % 
X reset control-o flag% 
inptrf _ ; 
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LOOP 

BEGIN 

IF inptpf THEI^ %user t/ped a control*o% 
BEGIf^ 

disiues (!♦ $**yser teraslnated process** I 
EXIT LOOP ; 
END I 
%1ncrement to next statement in branch you are 
processing which passed filter "proc"? or else ex1t% 

IF seqgen(8rs«) = endfll THEN EXIT LOOP ; 
%cdil some procedure to process current st Id I could 
as well have been any block of codel% 

process {sw»swst1d> $ 
end; 
% close sequence % 
ON SIGNAL ELSE » 
closeseq C&sw> I 
Section 8: Conditional Compiling 

You Biay dellialt blocks of code within procedures that will only 
be compiled If a constant Is TRUE or FALSE* If the code Is not 
co?»p1ledf of course 1t will not be part of the code file and will 
not be executed. 

First a constant must be defined with the SET construct Cat 
the beginning of the fllel as either zero f FALSE) or non-zero 
CTRUE). 

Then* code delimited by the string: 
%+naffie% 

where na»e Is the SET constant 
will only be compiled if the constant Is SET to a TRUE 
value* 
Slfflllarlyt code delimited by the string: 
%-nai8e% 

will only be compiled if the constant Is set to zero 
(FALSEI. 
For example t 

if the following statement appears at the beginning of the 
program: 

SET test=0; 
then a procedure In the prograia wight Include code celliRlted 
by this construct* e.g»: 

LIO statement $ Xnormal codet always cosiplledX 

LIG statement ; %norfflal codet always corBpiled% 
%-test% 

LIO stateiRent » %th1s statement yiLL be coarpl led% 

LIO statement ; %th1s stateaent yiLL be coispl led% 
%-test% 
%*test% 

LIO statefnent » Xthls statement will NOT be co«p1led% 

• 

LIO statement ♦ %th1s statement will NOT be coieplledl 
%+test% 
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LIO statement ♦ %noriaal codet always coraplLedl 
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